{ "openapi": "3.1.0", "info": { "title": "PromptLayer API", "description": "REST API for PromptLayer: prompt template management, request logging, observability, evaluations, and workflows.", "version": "1.0.0" }, "paths": { "/prompt-templates/{identifier}": { "get": { "tags": [ "prompt-templates" ], "summary": "Get Prompt Template Raw Data", "operationId": "get_prompt_template_raw", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "identifier", "description": "The identifier can be either the prompt name or the prompt id." }, "example": "support-response" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "title": "Version", "description": "Specific version number to retrieve. Mutually exclusive with `label`." }, "example": 2 }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "title": "Label", "description": "Release label name to retrieve (e.g. 'prod', 'staging'). Mutually exclusive with `version`." }, "example": "production" }, { "name": "resolve_snippets", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Resolve Snippets", "description": "When true (default), snippets are expanded in the returned prompt_template. When false, raw @@@snippet@@@ references are preserved." }, "example": false }, { "name": "include_llm_kwargs", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include LLM Kwargs", "description": "When true, includes provider-specific llm_kwargs in the response. Requires model metadata to be set on the template." }, "example": true } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPromptTemplateRawResponse" }, "examples": { "rawTemplate": { "summary": "Raw prompt template", "value": { "success": true, "id": 17, "prompt_name": "support-response", "version": 2, "workspace_id": 42, "prompt_template": { "type": "chat", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "You are a helpful support assistant." } ] }, { "role": "user", "content": [ { "type": "text", "text": "{user_message}" } ] } ] }, "metadata": { "model": { "provider": "openai", "name": "gpt-4o", "parameters": { "temperature": 0.2 } } }, "commit_message": "Improve support tone", "tags": [ "support" ], "created_at": "2025-03-15T10:30:00Z", "snippets": [], "llm_kwargs": null } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "prompt-templates" ], "summary": "Get Prompt Template by ID", "operationId": "get_prompt_templates__prompt_identifier__post", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "identifier", "description": "The identifier can be either the prompt name or the prompt id." } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GetPromptTemplate" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPromptTemplateResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/prompt-templates/{identifier}/labels": { "get": { "tags": [ "prompt-templates", "release-labels" ], "summary": "Get Prompt Template Labels", "operationId": "get_prompt_templates_labels_prompt_identifier__post", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "identifier", "description": "The identifier can be either the prompt name or the prompt id." } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPromptTemplateLabelResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Not Found" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/prompts/{prompt_id}/label": { "post": { "tags": [ "prompts", "labels" ], "summary": "Create a new label for a prompt", "operationId": "create_prompt_label", "parameters": [ { "name": "prompt_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_version_number": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "prompt_version_number", "name" ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "prompt_id": { "type": "integer" }, "prompt_version_id": { "type": "integer" } }, "required": [ "created_at", "id", "name", "prompt_id", "prompt_version_id" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/prompt-labels/{prompt_label_id}": { "patch": { "tags": [ "prompt-templates", "release-labels" ], "summary": "Move Prompt Template Labels", "operationId": "prompt_templates_labels_prompt_label_id__patch", "parameters": [ { "name": "prompt_label_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_label_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt_version_number": { "type": "integer" } }, "required": [ "prompt_version_number" ] } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "prompt_id": { "type": "integer" }, "prompt_version_id": { "type": "integer" } }, "required": [ "created_at", "id", "name", "prompt_id", "prompt_version_id" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "prompt-templates", "release-labels" ], "summary": "Delete Prompt Template Label", "operationId": "delete_prompt_templates_labels_prompt_label_id", "parameters": [ { "name": "prompt_label_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_label_id" } } ], "responses": { "204": { "description": "No Content", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/prompt-templates": { "post": { "tags": [ "rest", "prompt-templates" ], "summary": "Publish Prompt Template", "operationId": "publish_prompt_template_rest_prompt_templates_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplateResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/rest/prompt-templates/{identifier}": { "patch": { "tags": [ "rest", "prompt-templates" ], "summary": "Patch Prompt Template Version", "operationId": "patch_prompt_template_version", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "Identifier", "description": "The prompt template name or ID." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchPromptTemplateVersion" }, "examples": { "patchMessage": { "summary": "Patch one message by index", "value": { "messages": { "0": { "role": "system", "content": [ { "type": "text", "text": "You are a helpful assistant." } ] } }, "commit_message": "Updated system message" } }, "replaceMessages": { "summary": "Replace all messages", "value": { "messages": [ { "role": "system", "content": [ { "type": "text", "text": "New system prompt." } ] }, { "role": "user", "content": [ { "type": "text", "text": "{user_input}" } ] } ] } }, "tuneParameters": { "summary": "Update model parameters", "value": { "model_parameters": { "temperature": 0.7, "max_tokens": 500 }, "commit_message": "Tuned generation parameters" } }, "deploy": { "summary": "Deploy with release labels", "value": { "model_parameters": { "temperature": 0.5 }, "response_format": { "type": "json_object" }, "commit_message": "Deploy with JSON mode", "release_labels": [ "staging", "production" ] } } } } } }, "responses": { "201": { "description": "New version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplateResponse" }, "examples": { "patched": { "summary": "Prompt template version created", "value": { "id": 17, "prompt_name": "support-response", "prompt_version_id": 109, "version_number": 5, "tags": [], "release_labels": [ "staging" ], "prompt_template": { "type": "chat", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "You are a helpful assistant." } ] } ] }, "metadata": null, "commit_message": "Updated system message", "external_ids": [] } } } } } }, "400": { "description": "Validation error (e.g. conflicting fields, out-of-bounds index, wrong template type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/track-metadata": { "post": { "summary": "Track Metadata", "operationId": "trackMetadata", "tags": [ "metadata" ], "requestBody": { "required": true, "description": "Metadata tracking payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackMetadataRequest" }, "examples": { "metadata": { "summary": "Track metadata", "value": { "request_id": 12345, "metadata": { "session_id": "abc123", "user_id": "user123" } } } } } } }, "responses": { "200": { "description": "Metadata saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackResponse" }, "examples": { "tracked": { "summary": "Tracked", "value": { "success": true, "message": "Metadata tracked successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/track-group": { "post": { "summary": "Track Group", "operationId": "trackGroup", "tags": [ "group" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "integer", "description": "The unique identifier for the request." }, "group_id": { "type": "integer", "description": "The unique identifier for the group to be associated with the request." } }, "required": [ "request_id", "group_id" ] } } } }, "responses": { "200": { "description": "Group tracked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/track-prompt": { "post": { "summary": "Track Prompt", "operationId": "trackPrompt", "tags": [ "prompt" ], "requestBody": { "required": true, "description": "Prompt tracking payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackPromptRequest" }, "examples": { "track": { "summary": "Track prompt", "value": { "prompt_name": "support-response", "prompt_input_variables": { "user_message": "Hello" }, "request_id": 12345, "version": 2 } } } } } }, "responses": { "200": { "description": "Prompt association saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackResponse" }, "examples": { "tracked": { "summary": "Tracked", "value": { "success": true, "message": "Prompt tracked successfully" } } } } } }, "400": { "description": "Bad Request" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/track-score": { "post": { "summary": "Track Score", "operationId": "trackScore", "tags": [ "score" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "integer", "description": "The `request_id` from tracking a request." }, "score": { "type": "integer", "description": "The score you would like to give to this request (0 - 100).", "minimum": 0, "maximum": 100 }, "name": { "type": "string", "description": "A name for this request score. If not provided, the score will be tracked as `default`.", "optional": true } }, "required": [ "request_id", "score" ] } } } }, "responses": { "200": { "description": "Score tracked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports/name/{report_name}": { "delete": { "summary": "Delete Reports by Name", "operationId": "deleteReportsByName", "tags": [ "reports" ], "parameters": [ { "name": "report_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the report to archive." } ], "responses": { "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Report not found" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports": { "post": { "summary": "Create Evaluation Pipeline", "operationId": "createEvaluationPipeline", "tags": [ "reports" ], "requestBody": { "required": true, "description": "Evaluation pipeline creation payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationPipelineRequest" }, "examples": { "builtInScoring": { "summary": "Built-in scoring", "value": { "dataset_group_id": 123, "name": "Pipeline with Built-in Scoring", "columns": [ { "column_type": "LLM_ASSERTION", "name": "Accuracy Check", "configuration": { "source": "response", "prompt": "Is this response accurate?" }, "is_part_of_score": true }, { "column_type": "LLM_ASSERTION", "name": "Safety Check", "configuration": { "source": "response", "prompt": "Is this response safe?" }, "is_part_of_score": true } ] } }, "customScoring": { "summary": "Custom scoring", "value": { "dataset_group_id": 123, "name": "Pipeline with Custom Scoring", "columns": [ { "column_type": "LLM_ASSERTION", "name": "Accuracy Check", "configuration": { "source": "response", "prompt": "Is this response accurate?" } }, { "column_type": "LLM_ASSERTION", "name": "Safety Check", "configuration": { "source": "response", "prompt": "Is this response safe?" } } ], "score_configuration": { "code": "weights = {\"Accuracy Check\": 0.7, \"Safety Check\": 0.3}\ntotal_weight = weighted_sum = 0\nfor row in data:\n for col, weight in weights.items():\n if col in row:\n total_weight += weight\n if row[col] == True:\n weighted_sum += weight\nscore = (weighted_sum / total_weight * 100) if total_weight > 0 else 0\nreturn {\"score\": round(score, 2)}", "code_language": "PYTHON" } } } } } } }, "responses": { "201": { "description": "Evaluation pipeline created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvaluationPipelineResponse" }, "examples": { "created": { "summary": "Pipeline created", "value": { "success": true, "report_id": 456, "report_columns": [ { "id": 789, "name": "Accuracy Check", "column_type": "LLM_ASSERTION", "position": 1, "configuration": { "source": "response" } } ], "external_ids": [] } } } } } }, "400": { "description": "Bad Request - Invalid parameters, draft dataset version, or no datasets in group", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Dataset must have at least one non-draft version" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/report-columns": { "post": { "summary": "Add Column to Evaluation Pipeline", "operationId": "addReportColumn", "tags": [ "reports" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_id": { "type": "integer", "description": "The ID of the evaluation pipeline to add this column to.", "minimum": 1 }, "column_type": { "type": "string", "description": "The type of evaluation or transformation this column performs. Must be one of the supported column types.", "enum": [ "ABSOLUTE_NUMERIC_DISTANCE", "AI_DATA_EXTRACTION", "ASSERT_VALID", "CONVERSATION_SIMULATOR", "COALESCE", "CODE_EXECUTION", "COMBINE_COLUMNS", "COMPARE", "CONTAINS", "COSINE_SIMILARITY", "COUNT", "ENDPOINT", "MCP", "HUMAN", "JSON_PATH", "LLM_ASSERTION", "MATH_OPERATOR", "MIN_MAX", "PARSE_VALUE", "APPLY_DIFF", "PROMPT_TEMPLATE", "REGEX", "REGEX_EXTRACTION", "VARIABLE", "XML_PATH", "WORKFLOW", "CODING_AGENT" ] }, "name": { "type": "string", "description": "Display name for this column. Must be unique within the pipeline. This name is used to reference the column in subsequent steps.", "minLength": 1, "maxLength": 255 }, "configuration": { "type": "object", "description": "Column-specific configuration. The schema varies based on column_type. See documentation for each type's requirements.", "additionalProperties": true }, "position": { "type": "integer", "description": "Optional position for the column. If not specified, the column is added at the end. Cannot overwrite dataset columns.", "minimum": 0, "nullable": true } }, "required": [ "report_id", "column_type", "name", "configuration" ], "example": { "report_id": 456, "column_type": "PROMPT_TEMPLATE", "name": "Generate Answer", "configuration": { "template": { "name": "qa_template", "version_number": null }, "prompt_template_variable_mappings": { "question": "input_question" }, "engine": { "provider": "openai", "model": "gpt-4", "parameters": { "temperature": 0.7 } } } } } } } }, "responses": { "201": { "description": "Column added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "report_column": { "type": "object", "description": "Details of the created column including its ID and configuration" } } } } } }, "400": { "description": "Bad Request - Invalid column type, configuration validation failed, or column name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Report already has a column with that name" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Cannot overwrite dataset columns or missing permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "You can not overwrite dataset columns" } } } } } }, "404": { "description": "Not Found - Report not found or not accessible", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Report not found" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports/{report_id}/run": { "post": { "summary": "Run Full Evaluation", "operationId": "runReport", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the evaluation pipeline report to run." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the final report to be created. Must be between 1 and 255 characters in length.", "minLength": 1, "maxLength": 255 }, "dataset_id": { "type": [ "integer", "null" ], "description": "The ID of the dataset to use for the report. If not provided, uses the evaluation pipeline's default dataset." }, "refresh_dataset": { "type": [ "boolean", "null" ], "description": "Whether to refresh the dataset before running the report. Only applicable for dynamic datasets." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Report run initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report_id": { "type": "integer", "description": "The ID of the created final report." } }, "required": [ "success", "report_id" ] } } } }, "400": { "description": "Bad Request - Invalid data or report generation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "401": { "description": "Unauthorized - No requests found for the given criteria", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "403": { "description": "Forbidden - Can only run evaluation pipeline reports or dataset refresh not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "404": { "description": "Not Found - Report or dataset not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports/{report_id}": { "get": { "summary": "Get Evaluation", "operationId": "getReport", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the report to retrieve." } ], "responses": { "200": { "description": "Report retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "report": { "type": "object", "description": "The report data with all fields", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "is_blueprint": { "type": [ "boolean", "null" ] }, "deleted": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "score": { "type": [ "object", "null" ], "description": "Report score data" }, "score_configuration": { "type": [ "object", "null" ], "description": "Score configuration settings" }, "score_matrix": { "type": [ "array", "null" ], "description": "Score matrix for custom scoring" }, "score_calculation_error": { "type": [ "string", "null" ], "description": "Error message if score calculation failed" }, "parent_report_id": { "type": [ "integer", "null" ] }, "dataset_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "workspace_id": { "type": "integer" }, "prompt_registry_id": { "type": [ "integer", "null" ], "description": "ID of associated prompt registry" }, "prompt_version_number": { "type": [ "integer", "null" ], "description": "Version number of associated prompt" } }, "required": [ "id", "name", "deleted", "created_at", "updated_at", "workspace_id" ] }, "status": { "type": "string", "enum": [ "RUNNING", "COMPLETED" ], "description": "Overall status of the report execution" }, "stats": { "type": "object", "properties": { "status_counts": { "type": "object", "description": "Count of cells in each status", "properties": { "COMPLETED": { "type": "integer", "description": "Number of completed cells" }, "FAILED": { "type": "integer", "description": "Number of failed cells" }, "QUEUED": { "type": "integer", "description": "Number of queued cells" }, "RUNNING": { "type": "integer", "description": "Number of running cells" } }, "required": [ "COMPLETED", "FAILED", "QUEUED", "RUNNING" ] } }, "required": [ "status_counts" ] }, "report_columns": { "type": "array", "description": "Ordered list of column configurations for this report.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "report_id": { "type": "integer" }, "column_type": { "type": "string", "description": "Type of evaluation column (e.g. LLM_ASSERTION, PROMPT_TEMPLATE, COMPARE)" }, "name": { "type": "string" }, "position": { "type": "integer", "description": "Zero-based column order" }, "is_part_of_score": { "type": "boolean" }, "configuration": { "type": "object", "description": "Column-type-specific configuration" }, "score": { "type": "number", "nullable": true, "description": "Computed score for this column, if available" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "Report not found or not accessible" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete Evaluation Pipeline", "operationId": "deleteReport", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the evaluation pipeline to archive." } ], "responses": { "200": { "description": "Evaluation pipeline archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteReportResponse" }, "examples": { "archived": { "summary": "Archived", "value": { "success": true, "message": "Report archived successfully" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports/{report_id}/score": { "get": { "summary": "Get Evaluation Score", "operationId": "getReportScore", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the report to get the score for." } ], "responses": { "200": { "description": "Report score retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "score": { "type": "object", "properties": { "overall_score": { "type": [ "number", "null" ], "description": "The overall score of the report" }, "score_type": { "type": "string", "enum": [ "single_column", "multi_column", "custom", "none" ], "description": "Type of scoring used for this report" }, "has_custom_scoring": { "type": "boolean", "description": "Whether custom scoring logic was used" }, "details": { "type": "object", "oneOf": [ { "description": "Single column score details", "properties": { "column_name": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "score_type": { "type": [ "string", "null" ] }, "num_skipped": { "type": "integer" } } }, { "description": "Multi-column score details", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "column_name": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "score_type": { "type": [ "string", "null" ] }, "num_skipped": { "type": "integer" } } } } } }, { "description": "Custom score details", "properties": { "matrix": { "type": "array", "description": "Score matrix from custom scoring logic" }, "configuration": { "type": [ "object", "null" ], "description": "Custom scoring configuration" } } }, { "description": "No score details", "properties": { "message": { "type": "string" } } } ] } }, "required": [ "overall_score", "score_type", "has_custom_scoring", "details" ] } }, "required": [ "success", "message", "score" ] } } } }, "400": { "description": "Bad Request - Blueprint reports do not have scores" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Invalid workspace" }, "404": { "description": "Report not found" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/reports/{report_id}/rename": { "patch": { "summary": "Rename Evaluation Pipeline", "operationId": "renameReport", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the evaluation pipeline to rename." } ], "requestBody": { "required": true, "description": "Rename or retag payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameReportRequest" }, "examples": { "rename": { "summary": "Rename and retag", "value": { "name": "Customer support - production blueprint", "tags": [ "production", "support" ] } } } } } }, "responses": { "200": { "description": "Evaluation pipeline renamed or retagged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameReportResponse" }, "examples": { "renamed": { "summary": "Pipeline renamed", "value": { "success": true, "report": { "id": 456, "name": "Customer support - production blueprint", "tags": [ "production", "support" ] } } } } } } }, "400": { "description": "Validation error - neither name nor tags was provided" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/report-columns/{report_column_id}": { "patch": { "summary": "Edit Evaluation Pipeline Column", "operationId": "editReportColumn", "tags": [ "reports" ], "parameters": [ { "name": "report_column_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the report column to edit." } ], "requestBody": { "required": true, "description": "Column update payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditReportColumnRequest" }, "examples": { "codeColumn": { "summary": "Update a code execution column", "value": { "report_id": 456, "column_type": "CODE_EXECUTION", "name": "Strict JSON check", "configuration": { "code": "import json\ntry:\n json.loads(response)\n return True\nexcept Exception:\n return False", "language": "PYTHON" } } } } } } }, "responses": { "200": { "description": "Column updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditReportColumnResponse" }, "examples": { "updated": { "summary": "Column updated", "value": { "success": true, "report_column": { "id": 789, "name": "Strict JSON check", "column_type": "CODE_EXECUTION", "position": 3, "configuration": { "language": "PYTHON" } } } } } } } }, "400": { "description": "Validation failed (invalid type/configuration, duplicate name, etc.)" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "summary": "Delete Evaluation Pipeline Column", "operationId": "deleteReportColumn", "tags": [ "reports" ], "parameters": [ { "name": "report_column_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the report column to delete." } ], "responses": { "204": { "description": "Column deleted. No response body is returned." }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/datasets": { "get": { "summary": "List Datasets", "operationId": "listDatasets", "tags": [ "datasets" ], "parameters": [ { "name": "dataset_group_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific dataset group ID" }, { "name": "prompt_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific prompt ID" }, { "name": "prompt_version_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific prompt version ID" }, { "name": "prompt_label_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific prompt label ID" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific workspace ID. If not provided, uses the current user's workspace" }, { "name": "report_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific report ID (includes parent report ID)" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter datasets by name (case-insensitive partial match on dataset group name)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active" }, "description": "Filter datasets by status: 'active' (default) returns only active datasets, 'deleted' returns only deleted/archived datasets, 'all' returns both" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of items per page" }, { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } }, "required": [ "success", "message", "datasets", "page", "per_page", "total", "pages" ] } } } }, "400": { "description": "Invalid workspace_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/requests/{request_id}": { "get": { "summary": "Get Request", "operationId": "getRequest", "tags": [ "tracking" ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The ID of the request to retrieve.", "example": 12345 } ], "responses": { "200": { "description": "Request log detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLogDetailResponse" }, "examples": { "request": { "summary": "Request detail", "value": { "success": true, "prompt_blueprint": { "prompt_template": { "type": "chat", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello, world!" } ] } ] }, "metadata": { "model": { "provider": "openai", "name": "gpt-4", "parameters": {} } }, "inference_client_name": null }, "request_id": 12345, "provider": "openai", "model": "gpt-4", "input_tokens": 12, "output_tokens": 25, "tokens": 37, "price": 0.00123, "request_start_time": "2024-04-03T20:57:25Z", "request_end_time": "2024-04-03T20:57:26Z", "latency_ms": 1000, "trace_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/traces/{trace_id}": { "get": { "summary": "Get Trace", "operationId": "getTrace", "tags": [ "tracking" ], "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The trace ID to retrieve spans for.", "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } ], "responses": { "200": { "description": "Trace detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceDetailResponse" }, "examples": { "trace": { "summary": "Trace with spans", "value": { "success": true, "trace_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "spans": [ { "id": 1, "name": "llm_call", "span_id": "1a2b3c4d5e6f7a8b", "parent_id": null, "request_log_id": 12345, "start_time": "2024-04-03T20:57:25Z", "end_time": "2024-04-03T20:57:26Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/datasets/{dataset_id}/rows": { "get": { "summary": "Get Dataset Rows", "operationId": "getDatasetRows", "tags": [ "datasets" ], "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The ID of the dataset to retrieve rows from" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific workspace ID. Defaults to current user's workspace." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of rows per page (max 100)" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query for filtering rows" } ], "responses": { "200": { "description": "Paginated dataset rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRowsResponse" }, "examples": { "rows": { "summary": "Dataset rows", "value": { "success": true, "message": "success", "columns": [ "input", "expected_output" ], "rows": [ [ { "type": "dataset", "value": "What is PromptLayer?" }, { "type": "dataset", "value": "A prompt management platform" } ] ], "page": 1, "per_page": 10, "pages": 5, "total": 45 } } } } } }, "400": { "description": "Invalid workspace_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/evaluations/{evaluation_id}/rows": { "get": { "summary": "Get Evaluation Rows", "operationId": "getEvaluationRows", "tags": [ "evaluations" ], "parameters": [ { "name": "evaluation_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The ID of the evaluation to retrieve rows from" }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific workspace ID. Defaults to current user's workspace." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of rows per page (max 100)" } ], "responses": { "200": { "description": "Paginated evaluation rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationRowsResponse" }, "examples": { "rows": { "summary": "Evaluation rows", "value": { "success": true, "message": "success", "columns": [ "input", "expected_output", "accuracy", "relevance" ], "rows": [ [ { "type": "dataset", "value": "What is PromptLayer?" }, { "type": "dataset", "value": "A prompt management platform" }, { "type": "eval", "status": "PASSED", "value": 0.95 }, { "type": "eval", "status": "PASSED", "value": 0.88 } ] ], "page": 1, "per_page": 10, "pages": 3, "total": 25 } } } } } }, "400": { "description": "Invalid workspace_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/evaluations": { "get": { "summary": "List Evaluations", "operationId": "listEvaluations", "tags": [ "evaluations" ], "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter by specific workspace ID. If not provided, uses the current user's workspace" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter evaluations by name (case-insensitive partial match)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active" }, "description": "Filter evaluations by status: 'active' (default) returns only active evaluations, 'deleted' returns only deleted/archived evaluations, 'all' returns both" }, { "name": "include_runs", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "If true, include batch runs nested under each evaluation. Each run includes its full report data, status (RUNNING or COMPLETED), and cell status counts." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of items per page" }, { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/Evaluation" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } }, "required": [ "success", "message", "evaluations", "page", "per_page", "total", "pages" ] } } } }, "400": { "description": "Invalid workspace_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-groups": { "post": { "summary": "Create Dataset Group", "operationId": "createDatasetGroup", "tags": [ "datasets" ], "requestBody": { "required": true, "description": "Dataset group creation payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetGroupRequest" }, "examples": { "inFolder": { "summary": "Create inside a folder", "value": { "name": "Customer support eval set", "folder_id": 17 } } } } } }, "responses": { "201": { "description": "Dataset group created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetGroupResponse" }, "examples": { "created": { "summary": "Dataset group created", "value": { "success": true, "message": "Dataset group created successfully", "dataset_group": { "id": 123, "name": "Customer support eval set" }, "dataset": { "id": 456, "version_number": -1 }, "external_ids": [] } } } } } }, "400": { "description": "Bad Request - Invalid workspace_id or dataset with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-versions/from-file": { "post": { "summary": "Create Dataset Version from File", "operationId": "createDatasetVersionFromFile", "tags": [ "datasets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetVersionFromFileRequest" }, "examples": { "csvFile": { "summary": "Create from CSV file", "value": { "dataset_group_id": 123, "file_name": "support-eval.csv", "file_content_base64": "cXVlc3Rpb24sZXhwZWN0ZWRfYW5zd2VyCldoYXQgaXMgUHJvbXB0TGF5ZXI/LEEgcHJvbXB0IG1hbmFnZW1lbnQgcGxhdGZvcm0=" } }, "jsonFile": { "summary": "Create from JSON file", "value": { "dataset_group_id": 123, "file_name": "support-eval.json", "file_content_base64": "W3sicXVlc3Rpb24iOiJXaGF0IGlzIFByb21wdExheWVyPyIsImV4cGVjdGVkX2Fuc3dlciI6IkEgcHJvbXB0IG1hbmFnZW1lbnQgcGxhdGZvcm0ifV0=" } } } } } }, "responses": { "201": { "description": "Dataset version creation job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetVersionFromFileResponse" }, "examples": { "queued": { "summary": "File processing queued", "value": { "success": true, "message": "Dataset version creation job queued", "dataset_id": 456 } } } } } }, "400": { "description": "Bad Request - Invalid file format, file too large, or invalid base64 encoding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Failed to upload file or create dataset version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/dataset-versions/from-filter-params": { "post": { "summary": "Create Dataset Version from Filter Params", "operationId": "createDatasetVersionFromFilterParams", "tags": [ "datasets" ], "requestBody": { "required": true, "description": "Dataset version creation payload from request IDs or request-log filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetVersionFromFilterParamsRequest" }, "examples": { "explicitIds": { "summary": "Explicit request IDs", "value": { "dataset_group_id": 123, "request_log_ids": [ 1001, 1002, 1003 ] } }, "filteredHistory": { "summary": "Structured filter group", "value": { "dataset_group_id": 123, "filter_group": { "logic": "AND", "filters": [ { "field": "request_start_time", "operator": "between", "value": [ "2026-04-01T00:00:00Z", "2026-04-30T23:59:59Z" ] }, { "field": "tags", "operator": "in", "value": [ "staging" ] }, { "field": "metadata", "operator": "key_equals", "nested_key": "app_name", "value": "checkout" } ] }, "q": "timeout", "sort_by": "request_start_time", "sort_order": "desc" } } } } } }, "responses": { "201": { "description": "Dataset version creation queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetVersionFromFilterParamsResponse" }, "examples": { "queued": { "summary": "Dataset job queued", "value": { "success": true, "message": "Dataset version creation queued", "dataset_id": 456, "dataset_group_id": 123, "version_number": -1 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-versions/create-draft": { "post": { "summary": "Create Draft Dataset Version", "operationId": "createDraftDatasetVersion", "tags": [ "datasets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftDatasetVersionRequest" }, "examples": { "emptyDraft": { "summary": "Create an empty draft", "value": { "dataset_group_id": 123 } }, "copyFromSource": { "summary": "Create a draft from an existing dataset version", "value": { "dataset_group_id": 123, "source_dataset_id": 456 } } } } } }, "responses": { "201": { "description": "Empty draft created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDatasetVersionResponse" }, "examples": { "created": { "summary": "Empty draft created", "value": { "success": true, "message": "Draft dataset version created", "draft_dataset_id": 789 } } } } } }, "202": { "description": "Draft created and source rows are being copied asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDatasetVersionResponse" }, "examples": { "copying": { "summary": "Rows copying from source dataset", "value": { "success": true, "message": "Draft created; rows are being copied from the source dataset", "draft_dataset_id": 789 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "A draft version already exists for this dataset group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-versions/add-request-log": { "post": { "summary": "Add Request Log to Draft Dataset", "operationId": "addRequestLogToDatasetVersion", "tags": [ "datasets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddRequestLogToDatasetRequest" }, "examples": { "addRequestLog": { "summary": "Add request log row", "value": { "dataset_group_id": 123, "request_log_id": 98765 } } } } } }, "responses": { "201": { "description": "Request log added to draft dataset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDatasetVersionResponse" }, "examples": { "added": { "summary": "Request log added", "value": { "success": true, "message": "Request log added to draft dataset", "draft_dataset_id": 789 } } } } } }, "400": { "description": "Request log and dataset must belong to the same workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-versions/save-draft": { "post": { "summary": "Save Draft Dataset Version", "operationId": "saveDraftDatasetVersion", "tags": [ "datasets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveDraftDatasetVersionRequest" }, "examples": { "saveDraft": { "summary": "Publish draft dataset version", "value": { "dataset_group_id": 123 } } } } } }, "responses": { "202": { "description": "Dataset save job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDatasetVersionResponse" }, "examples": { "queued": { "summary": "Save queued", "value": { "success": true, "message": "Dataset save job queued", "draft_dataset_id": 789 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/prompt-templates": { "get": { "tags": [ "prompt-templates" ], "summary": "Get All", "operationId": "get_all_prompt_templates__get", "parameters": [ { "in": "query", "name": "page", "schema": { "type": "integer", "title": "Page" } }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "title": "Per Page" } }, { "in": "query", "name": "label", "schema": { "type": "string", "title": "Label" }, "description": "Filter prompt templates by release label (e.g., 'prod', 'dev', 'staging')" }, { "in": "query", "name": "name", "schema": { "type": "string", "title": "Name" }, "description": "Filter prompt templates by name (case-insensitive partial match)" }, { "in": "query", "name": "tags", "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "title": "Tags" }, "description": "Filter prompt templates by tags. Can be a single tag or a list of tags. Only templates whose tags contain all specified values are returned." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active", "title": "Status" }, "description": "Filter prompt templates by status: 'active' (default) returns only active templates, 'deleted' returns only deleted/archived templates, 'all' returns both" }, { "in": "query", "name": "external_source", "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id.", "required": false }, { "in": "query", "name": "external_id", "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source.", "required": false }, { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." }, { "name": "is_snippet", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, return snippets only. When false, exclude snippets. When omitted, return both prompts and snippets." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPromptTemplates" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/log-request": { "post": { "tags": [ "request" ], "summary": "Log Request", "operationId": "logRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogRequest" }, "examples": { "success": { "summary": "Successful chat request", "value": { "provider": "openai", "model": "gpt-4o", "api_type": "chat-completions", "input": { "type": "chat", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello!" } ] } ] }, "output": { "type": "chat", "messages": [ { "role": "assistant", "content": [ { "type": "text", "text": "Hi there! How can I help you?" } ] } ] }, "request_start_time": "2024-01-15T10:30:00Z", "request_end_time": "2024-01-15T10:30:05Z", "tags": [ "production" ], "metadata": { "session_id": "abc123" } } }, "failed": { "summary": "Failed request", "value": { "provider": "openai", "model": "gpt-4", "api_type": "chat-completions", "input": { "type": "chat", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello!" } ] } ] }, "output": { "type": "chat", "messages": [] }, "request_start_time": "2024-01-15T10:30:00Z", "request_end_time": "2024-01-15T10:30:30Z", "status": "ERROR", "error_type": "PROVIDER_TIMEOUT", "error_message": "Request timed out after 30 seconds" } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogRequestResponse" }, "examples": { "logged": { "summary": "Request logged", "value": { "id": 12345, "prompt_version": null, "status": "SUCCESS", "error_type": null, "error_message": null } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BadRequestError" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workflow-version-execution-results": { "get": { "summary": "Get Workflow Version Execution Results", "operationId": "getWorkflowVersionExecutionResults", "tags": [ "workflow" ], "parameters": [ { "name": "workflow_version_execution_id", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The unique identifier of the workflow version execution whose results you want to retrieve." }, { "name": "return_all_outputs", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When set to true, the response includes all output nodes' results. If omitted or set to false, only the main output is returned." } ], "responses": { "200": { "description": "Successful response with execution results.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the node execution." }, "value": { "description": "The output value of the node." }, "error_message": { "type": "string", "nullable": true, "description": "Error message if the node failed." }, "raw_error_message": { "type": "string", "nullable": true, "description": "Raw error message if the node failed." }, "is_output_node": { "type": "boolean", "description": "Whether this node is an output node." } } } }, { "description": "The main output value of the workflow execution when return_all_outputs is false." } ] } } } }, "202": { "description": "Execution is still in progress. At least one node is in a non-final status (QUEUED or RUNNING).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the node execution." }, "value": { "description": "The output value of the node." }, "error_message": { "type": "string", "nullable": true, "description": "Error message if the node failed." }, "raw_error_message": { "type": "string", "nullable": true, "description": "Raw error message if the node failed." }, "is_output_node": { "type": "boolean", "description": "Whether this node is an output node." } } } }, { "description": "The main output value of the workflow execution when return_all_outputs is false." } ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/rest/workflows": { "post": { "summary": "Create Workflow", "operationId": "createWorkflow", "tags": [ "workflow" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflow" }, "examples": { "simpleWorkflow": { "summary": "Create a simple workflow", "value": { "name": "greeting-workflow", "commit_message": "Initial version", "nodes": [ { "name": "greeting", "node_type": "VARIABLE", "is_output_node": true, "configuration": { "value": { "type": "string", "value": "Hello, World!" } }, "dependencies": [] } ], "release_labels": [ "production" ] } }, "multipleNodes": { "summary": "Create a workflow with multiple nodes", "value": { "name": "classifier-workflow", "nodes": [ { "name": "classify", "node_type": "PROMPT_TEMPLATE", "is_output_node": false, "configuration": { "template": { "prompt_name": "intent-classifier", "label": "production" } }, "dependencies": [ "user_message" ] }, { "name": "response", "node_type": "PROMPT_TEMPLATE", "is_output_node": true, "configuration": { "template": { "prompt_name": "response-generator", "label": "production" } }, "dependencies": [ "classify", "user_message" ] } ], "required_input_variables": { "user_message": "string" } } }, "newVersion": { "summary": "Create a new version", "value": { "workflow_name": "my-workflow", "commit_message": "v2 updates", "nodes": [ { "name": "greeting", "node_type": "VARIABLE", "is_output_node": true, "configuration": { "value": { "type": "string", "value": "Hello, World!" } }, "dependencies": [] } ], "release_labels": [ "staging" ] } } } } } }, "responses": { "201": { "description": "Workflow created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowResponse" }, "examples": { "created": { "summary": "Workflow created", "value": { "success": true, "workflow_id": 123, "workflow_name": "greeting-workflow", "workflow_version_id": 456, "version_number": 1, "base_version": null, "release_labels": [ "production" ], "nodes": [ { "id": "node-uuid", "name": "greeting", "node_type": "VARIABLE", "is_output_node": true } ], "required_input_variables": {}, "external_ids": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/rest/workflows/{workflow_id_or_name}": { "patch": { "summary": "Patch Workflow", "operationId": "patchWorkflow", "tags": [ "workflow" ], "parameters": [ { "name": "workflow_id_or_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID or name of the workflow to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWorkflow" }, "examples": { "updateNode": { "summary": "Update one node", "value": { "commit_message": "Updated prompt template version", "nodes": { "response_generator": { "configuration": { "template": { "prompt_name": "response-v2", "label": "production" } } } } } }, "addNode": { "summary": "Add a node", "value": { "commit_message": "Added logging node", "nodes": { "logger": { "node_type": "CODE_EXECUTION", "configuration": { "code": "print(f'Processing: {input_data}')", "language": "PYTHON" }, "dependencies": [ "input_data" ], "is_output_node": false } } } }, "removeNode": { "summary": "Remove a node", "value": { "commit_message": "Removed deprecated node", "nodes": { "old_processor": null } } }, "branchFromVersion": { "summary": "Branch from a specific version", "value": { "base_version": 5, "commit_message": "Hotfix based on v5", "nodes": { "output": { "configuration": { "value": { "type": "string", "value": "fixed" } } } } } } } } } }, "responses": { "201": { "description": "Workflow version created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowResponse" }, "examples": { "patched": { "summary": "Workflow version created", "value": { "success": true, "workflow_id": 123, "workflow_name": "greeting-workflow", "workflow_version_id": 456, "version_number": 3, "base_version": 2, "release_labels": [ "staging" ], "nodes": [ { "id": "node-uuid", "name": "greeting", "node_type": "VARIABLE", "is_output_node": true } ], "required_input_variables": {}, "external_ids": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workflows": { "get": { "summary": "List Workflows", "operationId": "listWorkflows", "tags": [ "workflow" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for pagination." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "description": "Number of items per page." }, { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." } ], "responses": { "200": { "description": "List of workflows retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the workflow" }, "workspace_id": { "type": "integer", "description": "ID of the workspace this workflow belongs to" }, "user_id": { "type": "integer", "nullable": true, "description": "ID of the user who created this workflow" }, "name": { "type": "string", "description": "Name of the workflow" }, "is_deleted": { "type": "boolean", "description": "Whether the workflow is deleted" }, "latest_version_number": { "type": "integer", "nullable": true, "description": "The latest version number of the workflow" }, "release_labels": { "type": "array", "items": { "type": "string" }, "description": "Array of release label names associated with the workflow" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this workflow." } }, "required": [ "id", "workspace_id", "name", "is_deleted", "release_labels" ] } }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Number of items per page" }, "total": { "type": "integer", "nullable": true, "description": "Total number of items" }, "pages": { "type": "integer", "description": "Total number of pages" }, "has_next": { "type": "boolean", "description": "Whether there is a next page" }, "has_prev": { "type": "boolean", "description": "Whether there is a previous page" }, "next_num": { "type": "integer", "nullable": true, "description": "Next page number if available" }, "prev_num": { "type": "integer", "nullable": true, "description": "Previous page number if available" } }, "required": [ "items", "page", "per_page", "pages", "has_next", "has_prev" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid pagination parameters" } }, "required": [ "success", "message" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid API key" } }, "required": [ "success", "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workflows/{workflow_id_or_name}": { "get": { "summary": "Get Agent", "operationId": "getWorkflow", "tags": [ "workflow" ], "parameters": [ { "name": "workflow_id_or_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agent ID or name.", "example": "my-workflow" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Specific version number to retrieve. Mutually exclusive with `label`.", "example": 3 }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release label name to retrieve (e.g. 'prod', 'staging'). Mutually exclusive with `version`.", "example": "production" } ], "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "workflow_id": { "type": "integer", "description": "Unique identifier for the agent" }, "workflow_name": { "type": "string", "description": "Name of the agent" }, "version": { "type": "integer", "description": "Version number" }, "workflow_version_id": { "type": "integer", "description": "Unique identifier for this version" }, "commit_message": { "type": "string", "nullable": true, "description": "Commit message for this version" }, "required_input_variables": { "type": "object", "nullable": true, "description": "Input variable names mapped to their types", "additionalProperties": { "type": "string" } }, "release_labels": { "type": "array", "items": { "type": "string" }, "description": "Release labels attached to this version" }, "created_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when this version was created" }, "nodes": { "type": "array", "description": "Full node definitions including configuration and dependencies", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the node" }, "workflow_version_id": { "type": "integer", "description": "Version ID this node belongs to" }, "name": { "type": "string", "description": "Node name (unique within a version)" }, "node_type": { "type": "string", "description": "Type of node (e.g. PROMPT_TEMPLATE, CODE_EXECUTION, VARIABLE)" }, "is_output_node": { "type": "boolean", "description": "Whether this node is an output node" }, "configuration": { "type": "object", "description": "Full node configuration (structure depends on node_type)" }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "Names of nodes this node depends on" } }, "required": [ "id", "name", "node_type", "is_output_node", "configuration", "dependencies" ] } }, "edges": { "type": "array", "description": "Connections between nodes with optional conditionals", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the edge" }, "source_node_name": { "type": "string", "description": "Name of the source node" }, "target_node_name": { "type": "string", "description": "Name of the target node" }, "is_and": { "type": "boolean", "description": "Whether all conditionals must be true (AND) or any (OR)" }, "conditionals": { "type": "array", "description": "Conditional rules for this edge", "items": { "type": "object" } } }, "required": [ "id", "source_node_name", "target_node_name", "is_and" ] } } }, "required": [ "success", "workflow_id", "workflow_name", "version", "workflow_version_id", "nodes", "edges" ] }, "examples": { "latest": { "summary": "Workflow", "value": { "success": true, "workflow_id": 123, "workflow_name": "my-workflow", "version_number": 3, "release_labels": [ "production" ], "nodes": [ { "name": "greeting", "node_type": "VARIABLE", "is_output_node": true, "configuration": { "value": { "type": "string", "value": "Hello, World!" } }, "dependencies": [] } ], "edges": [], "required_input_variables": { "user_message": "string" }, "external_ids": [] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workflows/{workflow_id_or_name}/labels": { "get": { "summary": "Get Agent Labels", "operationId": "getWorkflowLabels", "tags": [ "workflow", "release-labels" ], "parameters": [ { "name": "workflow_id_or_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The agent ID or name." } ], "responses": { "200": { "description": "Labels retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "release_labels": { "type": "array", "items": { "type": "object", "properties": { "release_label": { "type": "string", "description": "Label name (e.g. 'prod', 'staging')" }, "release_label_id": { "type": "integer", "description": "Unique identifier for the label" }, "workflow_version_id": { "type": "integer", "description": "Version ID this label points to" }, "workflow_version_number": { "type": "integer", "description": "Version number this label points to" } }, "required": [ "release_label", "release_label_id", "workflow_version_id", "workflow_version_number" ] } } }, "required": [ "success", "release_labels" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Agent not found" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/workflows/{workflow_name}/run": { "post": { "summary": "Run Workflow", "operationId": "runWorkflow", "tags": [ "workflow" ], "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The name of the workflow to execute." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflow" }, "examples": { "runLatest": { "summary": "Run latest version", "value": { "input_variables": { "user_message": "I need help with billing" }, "metadata": { "environment": "production" }, "return_all_outputs": false } }, "runLabel": { "summary": "Run production label", "value": { "workflow_label_name": "production", "input_variables": { "user_message": "Hello" } } }, "asyncCallback": { "summary": "Run asynchronously with callback", "value": { "input_variables": { "user_message": "Hello" }, "callback_url": "https://example.com/promptlayer/workflow-callback" } } } } } }, "responses": { "201": { "description": "Workflow execution created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowResponse" }, "examples": { "queued": { "summary": "Workflow execution started", "value": { "success": true, "message": "Workflow execution started", "warning": null, "workflow_version_execution_id": 98765 } } } } } }, "202": { "description": "Accepted. Returned when callback_url is provided and the workflow will deliver results asynchronously.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowResponse" }, "examples": { "accepted": { "summary": "Accepted for callback delivery", "value": { "success": true, "message": "Workflow execution accepted", "warning": null, "workflow_version_execution_id": 98765 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/spans-bulk": { "post": { "tags": [ "spans" ], "summary": "Create Spans Bulk", "operationId": "createSpansBulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpansBulk" }, "examples": { "withLogRequest": { "summary": "Span with log request", "value": { "spans": [ { "name": "llm_call", "context": { "trace_id": "d4b5e2a13c8f4e9ab7d61a2b3c4d5e6f", "span_id": "a1b2c3d45e6f7a8b", "trace_state": "promptlayer=enabled" }, "kind": "SpanKind.CLIENT", "parent_id": "parent123", "start_time": 1630000000000000000, "end_time": 1630000001000000000, "status": { "status_code": "StatusCode.OK", "description": "Success" }, "attributes": { "llm.provider": "openai", "llm.model": "gpt-3.5-turbo" }, "resource": { "attributes": { "service.name": "my-app" }, "schema_url": "https://opentelemetry.io/schemas/1.9.0" }, "log_request": { "provider": "openai", "model": "gpt-3.5-turbo", "input": { "type": "chat", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello!" } ] } ] }, "output": { "type": "chat", "messages": [ { "role": "assistant", "content": [ { "type": "text", "text": "Hi there! How can I help you?" } ] } ] }, "request_start_time": "2024-01-20T10:00:00Z", "request_end_time": "2024-01-20T10:00:01Z", "prompt_name": "greeting_prompt", "prompt_version_number": 1, "input_tokens": 10, "output_tokens": 12, "tags": [ "production", "greeting" ], "metadata": { "user_id": "user123", "session": "abc123" } } } ] } }, "inheritedTimes": { "summary": "Span with inherited request times", "value": { "spans": [ { "name": "llm_call", "context": { "trace_id": "d4b5e2a13c8f4e9ab7d61a2b3c4d5e6f", "span_id": "b2c3d4e56f7a8b9c", "trace_state": "" }, "kind": "SpanKind.INTERNAL", "parent_id": null, "start_time": 1630000000000000000, "end_time": 1630000001000000000, "status": { "status_code": "StatusCode.OK", "description": "Success" }, "attributes": { "llm.provider": "openai", "llm.model": "gpt-3.5-turbo" }, "resource": { "attributes": { "service.name": "my-app" }, "schema_url": "https://opentelemetry.io/schemas/1.9.0" }, "log_request": { "provider": "openai", "model": "gpt-3.5-turbo", "input": { "type": "chat", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Hello!" } ] } ] }, "output": { "type": "chat", "messages": [ { "role": "assistant", "content": [ { "type": "text", "text": "Hi there! How can I help you?" } ] } ] }, "prompt_name": "greeting_prompt", "prompt_version_number": 1, "input_tokens": 5, "output_tokens": 3 } } ] } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpansBulkResponse" }, "examples": { "created": { "summary": "Spans created", "value": { "success": true, "spans": [ { "id": 101, "name": "llm_call", "span_id": "a1b2c3d45e6f7a8b" } ], "request_logs": [ { "id": 12345, "span_id": "a1b2c3d45e6f7a8b" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/folders": { "post": { "tags": [ "folders" ], "summary": "Create Folder", "operationId": "create_folder_api_public_v2_folders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } } }, "responses": { "201": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderSuccessResponse" } } } }, "400": { "description": "Bad request - Invalid input or folder name already exists", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FolderExistsError" }, { "type": "string", "example": "Invalid workspace_id" } ] } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Parent folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentFolderNotFoundError" } } } }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/folders/{folder_id}": { "patch": { "tags": [ "folders" ], "summary": "Update Folder", "operationId": "update_folder_api_public_v2_folders_patch", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Folder ID", "description": "The ID of the folder to update." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderRequest" } } } }, "responses": { "200": { "description": "Folder updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderSuccessResponse" } } } }, "400": { "description": "Bad request - Folder with the same name already exists at this level", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderExistsError" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderNotFoundError" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/folders/entities": { "get": { "tags": [ "folders" ], "summary": "List Folder Entities", "operationId": "list_folder_entities_api_public_v2_folders_entities_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Workspace ID", "description": "The ID of the workspace to list entities from." } }, { "name": "folder_id", "in": "query", "required": false, "schema": { "type": "integer", "title": "Folder ID", "description": "The ID of the folder to list entities from. If not provided, lists entities at the workspace root level." } }, { "name": "filter_type", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "FOLDER", "PROMPT", "SNIPPET", "WORKFLOW", "DATASET", "REPORT", "AB_TEST", "INPUT_VARIABLE_SET" ] }, { "type": "array", "items": { "type": "string", "enum": [ "FOLDER", "PROMPT", "SNIPPET", "WORKFLOW", "DATASET", "REPORT", "AB_TEST", "INPUT_VARIABLE_SET" ] } } ], "title": "Filter Type", "description": "Filter entities by type. Can be a single type or a list of types. If not provided, all entity types are returned." } }, { "name": "search_query", "in": "query", "required": false, "schema": { "type": "string", "title": "Search Query", "description": "Search entities by name (case-insensitive partial match)." } }, { "name": "flatten", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Flatten", "description": "When true, returns all entities recursively within the folder hierarchy instead of only direct children." } }, { "name": "include_metadata", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Metadata", "description": "When true, includes type-specific metadata for each entity (e.g., prompt type, latest version number)." } }, { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." }, { "name": "tags", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "Filter entities by tags. Applies to entity types that support tags." }, { "name": "semantic_search", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Use semantic search instead of text matching. Requires search_query." }, { "name": "semantic_search_top_k", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Maximum number of semantic search results to consider." }, { "name": "semantic_search_threshold", "in": "query", "required": false, "schema": { "type": "number", "exclusiveMinimum": 0, "maximum": 2 }, "description": "Maximum semantic search distance threshold." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFolderEntitiesResponse" } } } }, "400": { "description": "Bad request - Missing or invalid workspace_id", "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/FolderNotFoundError" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "folders" ], "summary": "Move Folder Entities", "operationId": "move_folder_entities_api_public_v2_folders_entities_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveFolderEntitiesRequest" } } } }, "responses": { "200": { "description": "Entities moved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderEntitiesCountResponse" } } } }, "400": { "description": "Bad request - Missing workspace_id or invalid entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Folder or entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderNotFoundError" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "folders" ], "summary": "Delete Folder Entities", "operationId": "delete_folder_entities_api_public_v2_folders_entities_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFolderEntitiesRequest" } } } }, "responses": { "200": { "description": "Entities deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderEntitiesCountResponse" } } } }, "400": { "description": "Bad request - Folder is not empty (use cascade=true) or invalid entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal server error during deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/folders/resolve-id": { "get": { "tags": [ "folders" ], "summary": "Resolve Folder ID by Path", "operationId": "resolve_folder_id_api_public_v2_folders_resolve_id_get", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Workspace ID", "description": "The ID of the workspace containing the folder." } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "title": "Path", "description": "Dot-separated folder path to resolve (e.g., \"My Folder.Subfolder\")." } } ], "responses": { "200": { "description": "Folder ID resolved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveFolderIdResponse" } } } }, "400": { "description": "Bad request - Missing or invalid workspace_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Folder path not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/prompt-templates/{identifier}/snippet-usage": { "get": { "tags": [ "prompt-templates", "snippets" ], "summary": "Get Snippet Usage", "operationId": "get_snippet_usage", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "title": "identifier", "description": "The identifier can be either the prompt name or the prompt id." } }, { "name": "prompt_version_number", "in": "query", "required": false, "schema": { "type": "integer", "title": "prompt_version_number", "description": "Optional specific version number to check usage for" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSnippetUsageResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Access denied - Invalid workspace_id" }, "404": { "description": "Prompt template not found" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/traces": { "post": { "tags": [ "otlp" ], "summary": "Ingest Traces (OTLP)", "operationId": "ingestOtlpTraces", "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/x-protobuf", "application/json" ] }, "description": "The encoding of the request body. Use `application/x-protobuf` for binary protobuf or `application/json` for JSON." }, { "name": "Content-Encoding", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "gzip" ] }, "description": "Set to `gzip` if the request body is gzip-compressed." }, { "name": "close_after", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, all trace IDs in the request are marked as closed after ingestion. Subsequent span writes for those traces will be rejected with HTTP 409. Defaults to false." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtlpExportTraceServiceRequest" }, "examples": { "jsonTrace": { "summary": "OTLP JSON trace", "value": { "resourceSpans": [ { "resource": { "attributes": [ { "key": "service.name", "value": { "stringValue": "my-llm-app" } } ] }, "scopeSpans": [ { "scope": { "name": "openai.instrumentation", "version": "1.0.0" }, "spans": [ { "traceId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "spanId": "1a2b3c4d5e6f7a8b", "name": "chat gpt-4", "kind": 3, "startTimeUnixNano": "1700000000000000000", "endTimeUnixNano": "1700000001500000000", "attributes": [ { "key": "gen_ai.request.model", "value": { "stringValue": "gpt-4" } }, { "key": "gen_ai.provider.name", "value": { "stringValue": "openai" } }, { "key": "gen_ai.usage.input_tokens", "value": { "intValue": "25" } }, { "key": "gen_ai.usage.output_tokens", "value": { "intValue": "120" } } ], "status": { "code": 1 } } ] } ] } ] } } } }, "application/x-protobuf": { "schema": { "type": "string", "format": "binary", "description": "Binary-encoded ExportTraceServiceRequest protobuf message." } } } }, "responses": { "200": { "description": "Successful Response. When using protobuf, the response is a binary `ExportTraceServiceResponse`. When using JSON, the response is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtlpExportTraceServiceResponse" }, "examples": { "accepted": { "summary": "Accepted without rejections", "value": { "partialSuccess": null } }, "partial": { "summary": "Accepted with partial rejection", "value": { "partialSuccess": { "rejectedSpans": 1, "errorMessage": "Invalid spanId length" } } } } }, "application/x-protobuf": { "schema": { "type": "string", "format": "binary", "description": "Binary-encoded ExportTraceServiceResponse protobuf message." } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "One or more traces in the request are already closed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Trace already closed: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" }, "trace_ids": { "type": "array", "items": { "type": "string" }, "description": "The trace IDs that are already closed." } } }, "examples": { "traceClosed": { "summary": "Trace already closed", "value": { "error": "Trace already closed: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "trace_ids": [ "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" ] } } } } } }, "415": { "description": "Unsupported Content-Type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal server error during ingestion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/requests/search": { "post": { "summary": "Search Request Logs", "operationId": "searchRequestLogs", "tags": [ "tracking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequestLogsRequest" }, "examples": { "expensiveRequests": { "summary": "Find expensive requests", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "cost", "operator": "gte", "value": 0.1 }, { "field": "request_start_time", "operator": "after", "value": "2025-03-14T00:00:00Z" } ] }, "sort_by": "cost", "sort_order": "desc" } }, "metadata": { "summary": "Search by metadata", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "metadata", "operator": "key_equals", "value": "customer_123", "nested_key": "user_id" } ] } } }, "paginated": { "summary": "Paginate through results", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "engine", "operator": "is", "value": "gpt-4o" } ] }, "page": 3, "per_page": 25, "sort_by": "request_start_time", "sort_order": "desc" } } } } } }, "responses": { "200": { "description": "Paginated list of matching request logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequestLogsResponse" }, "examples": { "results": { "summary": "Search results", "value": { "success": true, "items": [ { "id": 12345, "engine": "gpt-4o", "provider_type": "openai", "input_tokens": 150, "output_tokens": 300, "price": 0.005, "request_start_time": "2025-03-15T10:30:00Z", "request_end_time": "2025-03-15T10:30:01Z", "latency": 1.234, "tags_array": [ "production" ], "metadata": [ { "user_id": "customer_123" } ], "scores": [], "prompt_name": "support-response" } ], "page": 1, "pages": 5, "per_page": 25, "total": 112, "has_next": true, "has_prev": false, "next_num": 2, "prev_num": null } } } } } }, "400": { "description": "Invalid filter or search parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/api/public/v2/requests/analytics": { "post": { "summary": "Request Analytics", "operationId": "getRequestAnalytics", "tags": [ "tracking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLogQuery" }, "examples": { "spend": { "summary": "Spend on GPT-4o this week", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "engine", "operator": "is", "value": "gpt-4o" }, { "field": "request_start_time", "operator": "between", "value": [ "2025-03-08T00:00:00Z", "2025-03-15T00:00:00Z" ] } ] } } }, "latency": { "summary": "p90 latency for production traffic", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "tags", "operator": "contains", "value": "production" } ] } } } } } } }, "responses": { "200": { "description": "Aggregated analytics for the matching request logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestAnalyticsResponse" }, "examples": { "analytics": { "summary": "Aggregated analytics", "value": { "success": true, "chartInterval": { "interval": "day", "bucketSizeMs": 86400000, "bucketMinutes": null }, "averageLatency": 1.2, "totalCost": 12.34, "totalTokens": 120000, "totalRequests": 2500, "totalCachedTokens": 15000, "totalThinkingTokens": 3000, "cacheTokenRatio": 0.18, "stats": [ { "date": "2025-03-15", "requests": 120, "tokens": 5400, "inputTokens": 3000, "outputTokens": 2400, "cost": 0.84, "latency": 1.1 } ], "mostUsedModels": [ [ "gpt-4o", 2500 ] ], "modelRequestsByDay": { "gpt-4o": [ [ "2025-03-15", 120 ] ] }, "latency": { "average_latency": { "2025-03-15": 1.2 }, "p50_latency": { "2025-03-15": 0.9 }, "p90_latency": { "2025-03-15": 2.1 }, "p95_latency": { "2025-03-15": 2.6 } } } } } } } }, "400": { "description": "Invalid filter or unsupported analytics filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/skill-collections": { "get": { "summary": "List Skill Collections", "operationId": "listSkillCollectionsPublic", "tags": [ "skill-collections" ], "responses": { "200": { "description": "List of skill collections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillCollectionsResponse" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "403": { "description": "Invalid workspace_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "parameters": [ { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." } ] }, "post": { "summary": "Create Skill Collection", "operationId": "createSkillCollectionPublic", "tags": [ "skill-collections" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillCollectionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateSkillCollectionMultipartRequest" } } } }, "responses": { "201": { "description": "Skill collection created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillCollectionResponse" } } } }, "400": { "description": "Validation or business rule error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "403": { "description": "Invalid workspace_id or plan limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "415": { "description": "Unsupported content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/skill-collections/{identifier}": { "get": { "summary": "Get Skill Collection", "operationId": "getSkillCollectionPublic", "tags": [ "skill-collections" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill collection UUID, name, or root_path.", "example": "customer-support-skills" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "zip" ] }, "description": "Omit this parameter for JSON, or use `zip` for an archive download.", "example": "json" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fetch a version pinned by release label. Mutually exclusive with `version`.", "example": "production" }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Fetch a specific version number. Mutually exclusive with `label`.", "example": 2 } ], "responses": { "200": { "description": "JSON payload or ZIP archive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSkillCollectionResponse" }, "examples": { "json": { "summary": "Skill collection JSON", "value": { "success": true, "skill_collection": { "id": "5e1a2f7b-9c4d-4a8f-85c2-9d91d2bf6c6f", "name": "customer-support-skills", "root_path": "/support" }, "files": [ { "path": "skills/refund-policy.md", "content": "Refund policy guidance..." } ], "version": { "number": 2, "label": "production" } } } } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "patch": { "summary": "Update Skill Collection", "operationId": "updateSkillCollectionPublic", "tags": [ "skill-collections" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill collection UUID, name, or root_path." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillCollectionRequest" } } } }, "responses": { "200": { "description": "Skill collection updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillCollectionResponse" } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "403": { "description": "Invalid workspace_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "404": { "description": "Skill collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/skill-collections/{identifier}/versions": { "post": { "summary": "Save Skill Collection Version", "operationId": "saveSkillCollectionVersionPublic", "tags": [ "skill-collections" ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill collection UUID, name, or root_path." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSkillCollectionVersionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SaveSkillCollectionVersionMultipartRequest" } } } }, "responses": { "201": { "description": "Skill collection version created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSkillCollectionVersionResponse" } } } }, "400": { "description": "Validation or business rule error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "401": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "403": { "description": "Invalid workspace_id or plan limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "404": { "description": "Skill collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "415": { "description": "Unsupported content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/requests/suggestions": { "get": { "summary": "Search Request Suggestions", "operationId": "getRequestSearchSuggestions", "tags": [ "tracking" ], "parameters": [ { "name": "field", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "engine", "provider_type", "prompt_id", "prompt", "tags", "metadata_keys", "status", "tool_names", "output_keys", "input_variable_keys", "metadata_values", "output_values", "input_variable_values" ] }, "description": "Request log field to get suggestions for.", "example": "tags" }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive prefix to filter suggestions.", "example": "prod" }, { "name": "metadata_key", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required when field is metadata_values, output_values, or input_variable_values. Specifies which key to get values for.", "example": "user_id" }, { "name": "prompt_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter suggestions to a specific prompt template (only used when field is prompt)." }, { "name": "filter_group", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON-encoded filter group to scope suggestions to matching requests.", "example": "{\"logic\":\"AND\",\"filters\":[{\"field\":\"engine\",\"operator\":\"is\",\"value\":\"gpt-4o\"}]}" } ], "responses": { "200": { "description": "Autocomplete suggestions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequestSuggestionsResponse" }, "examples": { "tags": { "summary": "Tag suggestions", "value": { "success": true, "values": [ "production", "staging", "prod-v2" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/api/public/v2/tool-registry": { "get": { "tags": [ "tool-registry" ], "summary": "List Tool Registries", "operationId": "list_tool_registries", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_registries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "workspace_id": { "type": "integer" }, "folder_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this tool." } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "parameters": [ { "name": "created_by_email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by the creator's email address." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or after this timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources created at or before this timestamp." }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or after this timestamp." }, { "name": "updated_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter resources updated at or before this timestamp." }, { "name": "external_source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID source to filter by. Must be provided with external_id." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External ID value to filter by. Must be provided with external_source." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "id" ] }, "description": "Sort field." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction." } ] }, "post": { "tags": [ "tool-registry" ], "summary": "Create Tool Registry", "operationId": "create_tool_registry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "tool_definition" ], "properties": { "name": { "type": "string", "description": "Tool name (unique per workspace)" }, "tool_definition": { "type": "object", "description": "Tool definition in OpenAI function-calling format" }, "description": { "type": "string", "description": "Optional human-readable description of the tool", "nullable": true }, "folder_id": { "type": "integer", "description": "Folder ID to place tool in", "nullable": true }, "commit_message": { "type": "string", "description": "Commit message for the initial version", "nullable": true }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." }, "execution": { "type": "object", "description": "Optional sandbox-executable body for the tool. When set, PromptLayer auto-runs the body between LLM turns. See the Auto Tool Execution feature page.", "nullable": true, "required": [ "type", "language", "code" ], "properties": { "type": { "type": "string", "enum": [ "code" ] }, "language": { "type": "string", "enum": [ "python", "javascript" ] }, "code": { "type": "string", "description": "The function BODY only — the signature `def (args):` (Python) or `function (args) { ... }` (JavaScript) is generated automatically. The LLM's arguments arrive as a single `args` object." } } } } } } } }, "responses": { "201": { "description": "Tool created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_registry": { "type": "object" }, "version": { "type": "object" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings for the tool." } }, "required": [ "external_ids" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "External ID conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/tool-registry/{identifier}": { "get": { "tags": [ "tool-registry" ], "summary": "Get Tool Registry", "operationId": "get_tool_registry", "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" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_registry": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "workspace_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "labels": { "type": "array", "items": { "type": "object" } }, "version": { "type": "object", "nullable": true, "description": "Resolved version object — includes `tool_definition` and (if set) `execution: { type, language, code }`." }, "tool_definition": { "type": "object", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/prompt-templates/by-external-id/{source}/{external_id}": { "put": { "tags": [ "external-ids", "prompt-templates" ], "summary": "Upsert Prompt Template by External ID", "operationId": "upsert_prompt_template_by_external_id", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplate" } } } }, "responses": { "200": { "description": "Prompt template updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplateResponse" } } } }, "201": { "description": "Prompt template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptTemplateResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/prompt-templates/{prompt_template_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Prompt Template External ID", "operationId": "attach_prompt_template_id_external_id", "parameters": [ { "name": "prompt_template_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_template_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Prompt Template External IDs", "operationId": "list_prompt_template_id_external_ids", "parameters": [ { "name": "prompt_template_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_template_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/prompt-templates/{prompt_template_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Prompt Template External ID", "operationId": "delete_prompt_template_id_external_id", "parameters": [ { "name": "prompt_template_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "prompt_template_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/folders/{folder_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Folder External ID", "operationId": "attach_folder_id_external_id", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "folder_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Folder External IDs", "operationId": "list_folder_id_external_ids", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "folder_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/folders/{folder_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Folder External ID", "operationId": "delete_folder_id_external_id", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "folder_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workflows/{workflow_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Workflow External ID", "operationId": "attach_workflow_id_external_id", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "workflow_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Workflow External IDs", "operationId": "list_workflow_id_external_ids", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "workflow_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workflows/{workflow_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Workflow External ID", "operationId": "delete_workflow_id_external_id", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "workflow_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/dataset-groups/{dataset_group_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Dataset Group External ID", "operationId": "attach_dataset_group_id_external_id", "parameters": [ { "name": "dataset_group_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "dataset_group_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Dataset Group External IDs", "operationId": "list_dataset_group_id_external_ids", "parameters": [ { "name": "dataset_group_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "dataset_group_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/dataset-groups/{dataset_group_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Dataset Group External ID", "operationId": "delete_dataset_group_id_external_id", "parameters": [ { "name": "dataset_group_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "dataset_group_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reports/{report_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Report External ID", "operationId": "attach_report_id_external_id", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "report_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Report External IDs", "operationId": "list_report_id_external_ids", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "report_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reports/{report_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Report External ID", "operationId": "delete_report_id_external_id", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "report_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/tool-registry/{tool_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Tool Registry External ID", "operationId": "attach_tool_id_external_id", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "tool_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Tool Registry External IDs", "operationId": "list_tool_id_external_ids", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "tool_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/tool-registry/{tool_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Tool Registry External ID", "operationId": "delete_tool_id_external_id", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "tool_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/skill-collections/{skill_collection_id}/external-ids": { "post": { "tags": [ "external-ids" ], "summary": "Attach Skill Collection External ID", "operationId": "attach_skill_collection_id_external_id", "parameters": [ { "name": "skill_collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "skill_collection_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachExternalIdRequest" } } } }, "responses": { "201": { "description": "External ID attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdAttachResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "external-ids" ], "summary": "List Skill Collection External IDs", "operationId": "list_skill_collection_id_external_ids", "parameters": [ { "name": "skill_collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "skill_collection_id" } } ], "responses": { "200": { "description": "External IDs for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdsListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/public/v2/skill-collections/{skill_collection_id}/external-ids/{source}/{external_id}": { "delete": { "tags": [ "external-ids" ], "summary": "Delete Skill Collection External ID", "operationId": "delete_skill_collection_id_external_id", "parameters": [ { "name": "skill_collection_id", "in": "path", "required": true, "schema": { "type": "string", "title": "skill_collection_id" } }, { "name": "source", "in": "path", "required": true, "schema": { "type": "string", "title": "source", "minLength": 1, "maxLength": 128 }, "description": "External ID source." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "title": "external_id", "minLength": 1, "maxLength": 512 }, "description": "External ID value. URL-encode any reserved path characters." } ], "responses": { "200": { "description": "External ID detached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdDeleteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "404": { "description": "Entity Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reports/{report_id}/score-card": { "patch": { "summary": "Configure Custom Scoring", "operationId": "updateReportScoreCard", "tags": [ "reports" ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the evaluation pipeline to update." } ], "requestBody": { "required": true, "description": "Score-card configuration payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportScoreCardRequest" }, "examples": { "weighted": { "summary": "Weighted scoring", "value": { "column_names": [ "Accuracy Check", "Style Check" ], "code": "weights = {\"Accuracy Check\": 0.7, \"Style Check\": 0.3}\ntotal_weight = weighted_sum = 0\nfor row in data:\n for col_name, weight in weights.items():\n if col_name in row and isinstance(row[col_name], bool):\n total_weight += weight\n if row[col_name]:\n weighted_sum += weight\nscore = (weighted_sum / total_weight * 100) if total_weight > 0 else 0\nreturn {\"score\": score}", "code_language": "PYTHON" } }, "allMustPass": { "summary": "All checks must pass", "value": { "column_names": [ "Accuracy Check", "Safety Check", "Format Check" ], "code": "check_columns = [\"Accuracy Check\", \"Safety Check\", \"Format Check\"]\npassed_rows = 0\nfor row in data:\n if all(row.get(col) == True for col in check_columns if col in row):\n passed_rows += 1\nscore = (passed_rows / len(data) * 100) if data else 0\nreturn {\"score\": score}", "code_language": "PYTHON" } } } } } }, "responses": { "200": { "description": "Score card updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportScoreCardResponse" }, "examples": { "updated": { "summary": "Score card updated", "value": { "success": true, "report": { "id": 456, "name": "My Evaluation Pipeline", "score_configuration": { "code": "return {\"score\": 85.5}", "code_language": "PYTHON" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/dataset-versions/add-trace": { "post": { "summary": "Add Trace to Draft Dataset", "operationId": "addTraceToDatasetVersion", "tags": [ "datasets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTraceToDatasetRequest" }, "examples": { "addTrace": { "summary": "Add a full trace as a dataset row", "value": { "dataset_group_id": 123, "trace_id": "abc123def456" } }, "addSpan": { "summary": "Add a specific span subtree as a dataset row", "value": { "dataset_group_id": 123, "trace_id": "abc123def456", "span_id": "span789xyz" } } } } } }, "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/tables": { "post": { "tags": [ "smart-tables" ], "summary": "Create Table", "description": "Create a new Table. A default sheet with one text column is created automatically. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/TableDetail" } } } } } }, "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 Tables in the workspace. Supports cursor-based pagination and optional filtering by folder or prompt column. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/Table" } }, "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/TableDetail" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Table not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "description": "Get Table. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace." }, "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/TableDetail" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Table not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "description": "Update Table. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace." }, "delete": { "tags": [ "smart-tables" ], "summary": "Delete Table", "description": "Delete a Table. This soft deletes the table and removes it from active list responses. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "delete_table", "parameters": [ { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Table deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Workspace access denied or missing delete permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Failed to delete table", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/Sheet" } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/TableImportOperation" }, "sheet": { "$ref": "#/components/schemas/Sheet" } } } } } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/TableImportOperation" } } } } } }, "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/Sheet" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Table or sheet not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Get Sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace." }, "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/Sheet" }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Table or sheet not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Update Sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace." }, "delete": { "tags": [ "smart-tables" ], "summary": "Delete Sheet", "description": "Delete a sheet. This soft deletes the sheet and removes it from active sheet list responses. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "delete_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 deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Workspace access denied or missing edit permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Failed to delete sheet", "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. By default, system-managed metadata columns such as price and latency columns are excluded; pass `include_system_columns=true` to include them. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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": "include_system_columns", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include system-managed metadata columns such as price and latency columns for prompt-template outputs." }, { "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/Column" } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/Column" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/Cell" } }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." } } } } } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/Column" }, "requires_recalculation": { "type": "boolean" }, "affected_column_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." } } } } } }, "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" } } } } } }, "delete": { "tags": [ "smart-tables" ], "summary": "Delete Column", "description": "Delete a column and its cells. The operation creates a new sheet version and may mark downstream dependent cells as stale. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "delete_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" } } ], "responses": { "200": { "description": "Column deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "stale_count": { "type": "integer", "description": "Number of stale cells on the sheet after downstream dependency propagation." }, "version": { "type": "integer", "description": "Current sheet version_count after the column is deleted." } } } } } }, "400": { "description": "Column cannot be deleted or stored score configuration is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Workspace access denied or missing edit permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table, sheet, or column not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Failed to delete column", "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 to cell. For prompt-template column cells, each cell can include a `request_metrics` object with price, latency, and token usage when available. Pass `include_columns=true` on the first page to receive column metadata alongside rows. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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": "include_system_columns", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include system-managed metadata columns such as price and latency columns for prompt-template outputs." }, { "name": "include_execution_metadata_aggregates", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include sheet-level and per-column aggregates for execution metrics such as price and latency." }, { "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) → cell object.", "additionalProperties": { "$ref": "#/components/schemas/Cell" } } } } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "row_count": { "type": "integer" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/Column" } }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." }, "execution_metadata_aggregates": { "allOf": [ { "$ref": "#/components/schemas/ExecutionMetadataAggregates" } ], "description": "Sheet-level and per-column aggregates for price and latency metrics. Only present when `include_execution_metadata_aggregates=true`." } } } } } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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–100).", "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 → 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/Cell" } } } } }, "cell_count": { "type": "integer" }, "row_count": { "type": "integer" }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." } } } } } }, "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/Cell" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Cell not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Retrieve a single cell by ID. For prompt-template column cells, the response includes a `request_metrics` object with price, latency, and token usage when available. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace." }, "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; computed cells are recalculated automatically. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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/Cell" }, "version": { "type": "integer", "description": "Current sheet version_count for this response. It matches the sheet's version_count after any committed changes." }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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": { "200": { "description": "No cells to recalculate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "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" } } } } } }, "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. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "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": { "200": { "description": "No cells to recalculate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "202": { "description": "Recalculation started", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "execution_id": { "type": "string" }, "cell_count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Table, sheet, or cell not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/operations": { "get": { "summary": "List Table Sheet Operations", "description": "List active recalculation operations and cell status counts for a Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "listTableSheetOperations", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTableSheetOperationsResponse" } } } }, "400": { "description": "Invalid workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create Table Sheet Operation", "description": "Queue a recalculation operation for selected columns, rows, and cell statuses. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "createTableSheetOperation", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetOperationRequest" } } } }, "responses": { "200": { "description": "No operation was queued or confirmation is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetOperationResponse" } } } }, "202": { "description": "Operation queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetOperationResponse" } } } }, "400": { "description": "Invalid request, query parameter, or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "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}/operations/{operation_id}": { "get": { "summary": "Get Table Sheet Operation", "description": "Poll a Table sheet recalculation operation by operation ID. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "getTableSheetOperationStatus", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Operation ID." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTableSheetOperationResponse" } } } }, "400": { "description": "Invalid workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table, sheet, or operation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Cancel Table Sheet Operation", "description": "Cancel an active Table sheet recalculation operation. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "cancelTableSheetOperation", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Operation ID." } ], "responses": { "200": { "description": "Operation cancelled or no active operation found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelTableSheetOperationResponse" } } } }, "400": { "description": "Invalid workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/score": { "get": { "summary": "Get Table Sheet Score", "description": "Retrieve the current score payload for a Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "getTableSheetScore", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSheetScoreResponse" } } } }, "400": { "description": "Invalid workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "summary": "Configure Table Sheet Score", "description": "Configure scoring for a Table sheet. This endpoint updates the configuration and returns whether recalculation is required; it does not queue score calculation. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "configureTableSheetScore", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureTableSheetScoreRequest" } } } }, "responses": { "200": { "description": "Score configuration updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureTableSheetScoreResponse" } } } }, "400": { "description": "Invalid score configuration or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table, sheet, or score column not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Failed to update score configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Recalculate Table Sheet Score", "description": "Queue recalculation for an existing Table sheet score configuration. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "recalculateTableSheetScore", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "responses": { "202": { "description": "Score recalculation queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculateTableSheetScoreResponse" } } } }, "400": { "description": "Score is not configured or score configuration is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Failed to queue score calculation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/versions": { "get": { "summary": "List Table Sheet Versions", "description": "List saved versions for a Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "listTableSheetVersions", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor returned from the previous page. Public table cursors encode the current sort, order, cursor value, and a hash of the active filters; reuse the cursor with the same sort, order, and filter parameters from the previous request." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of versions to return." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "version_number" ], "default": "version_number" }, "description": "Sort field. Currently supports version_number." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort order." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTableSheetVersionsResponse" } } } }, "400": { "description": "Invalid cursor, query parameter, sort/order, filter set, or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create Table Sheet Version", "description": "Create a named Table sheet version, or restore from an existing version while creating a new version. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "createTableSheetVersion", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetVersionRequest" } } } }, "responses": { "201": { "description": "Version created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTableSheetVersionResponse" } } } }, "400": { "description": "Invalid request body or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table, sheet, or source version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/versions/{version_id}": { "get": { "summary": "Get Table Sheet Version", "description": "Retrieve one Table sheet version, including its snapshot. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "getTableSheetVersion", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet version ID." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTableSheetVersionResponse" } } } }, "400": { "description": "Invalid workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table, sheet, or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/versions/score-history": { "get": { "summary": "Get Table Sheet Score History", "description": "Retrieve score-history points across Table sheet versions. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "getTableSheetVersionScoreHistory", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." }, { "name": "max_points", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 50, "maximum": 5000, "default": 1200 }, "description": "Maximum points to return." }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "last_25", "last_50", "last_100", "last_250" ], "default": "all" }, "description": "History range." }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "raw", "min_max_bucket" ], "default": "auto" }, "description": "Point resolution." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSheetScoreHistoryResponse" } } } }, "400": { "description": "Invalid query parameter or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/imports/file": { "post": { "summary": "Import File Into Table Sheet", "description": "Start an asynchronous CSV import into an existing Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "createTableSheetFileImport", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetFileImportRequest" } } } }, "responses": { "202": { "description": "File import queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSheetImportStartResponse" } } } }, "400": { "description": "Invalid request body, file, or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Failed to upload file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/imports/request-logs": { "post": { "summary": "Import Request Logs Into Table Sheet", "description": "Start an asynchronous request-history import into an existing Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.", "operationId": "createTableSheetRequestLogImport", "tags": [ "tables" ], "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your PromptLayer API key. The key's workspace scopes table resources for this request." }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table ID." }, { "name": "sheet_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Table sheet ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTableSheetRequestLogImportRequest" } } } }, "responses": { "202": { "description": "Request-history import queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableSheetImportStartResponse" } } } }, "400": { "description": "Invalid request body, request logs, or workspace context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Table or sheet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/tool-registry/{identifier}/versions": { "post": { "tags": [ "tool-registry" ], "summary": "Create Tool Version", "operationId": "create_tool_version", "parameters": [ { "required": true, "schema": { "type": "string", "title": "X-Api-Key" }, "name": "X-API-KEY", "in": "header" }, { "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": { "type": "object", "description": "Optional sandbox-executable body. When set, PromptLayer auto-runs the body between LLM turns whenever a prompt uses this version. See Auto Tool Execution.", "nullable": true, "required": [ "type", "language", "code" ], "properties": { "type": { "type": "string", "enum": [ "code" ] }, "language": { "type": "string", "enum": [ "python", "javascript" ] }, "code": { "type": "string", "description": "The function BODY only — the signature `def (args):` (Python) or `function (args) { ... }` (JavaScript) is generated automatically. LLM arguments arrive as a single `args` object." } } }, "commit_message": { "type": "string", "description": "Commit message for the new version", "nullable": true } } } } } }, "responses": { "201": { "description": "Version created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "version": { "type": "object" } } } } } }, "404": { "description": "Tool not found" } } } }, "/api/public/v2/tool-registry/{identifier}/test-execute": { "post": { "tags": [ "tool-registry" ], "summary": "Test Execute Tool", "operationId": "test_execute_tool", "parameters": [ { "required": true, "schema": { "type": "string", "title": "X-Api-Key" }, "name": "X-API-KEY", "in": "header" }, { "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). Falls back to latest if neither label nor version supplied." } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string", "description": "Resolve by specific version number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "object", "description": "Arguments passed to the tool body. Same shape the LLM would emit — keys match the tool's parameter names.", "additionalProperties": true }, "execution": { "type": "object", "description": "In-flight override of the stored execution config. Lets you test unsaved code.", "nullable": true, "required": [ "type", "language", "code" ], "properties": { "type": { "type": "string", "enum": [ "code" ] }, "language": { "type": "string", "enum": [ "python", "javascript" ] }, "code": { "type": "string" } } }, "tool_definition": { "type": "object", "description": "In-flight override of the stored tool definition. Used to test against a different function name without saving.", "nullable": true } } } } } }, "responses": { "200": { "description": "Tool executed (success or user-code error). User-code errors return status=\"error\" inside the result object — they do NOT raise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "error" ] }, "result": { "description": "The tool body's return value (any JSON-serializable type). Present on status=\"success\".", "nullable": true }, "stdout": { "type": "string" }, "stderr": { "type": "string" }, "duration_ms": { "type": "integer" }, "error": { "type": "object", "nullable": true, "description": "Present on status=\"error\". Includes `type` and `message`." } } } } } } } }, "400": { "description": "Missing execution config or function name" }, "404": { "description": "Tool or version not found" }, "502": { "description": "Sandbox infrastructure failure" } } } }, "/api/public/v2/traces/{trace_id}/close": { "post": { "summary": "Close Trace", "operationId": "closeTrace", "tags": [ "tracking" ], "description": "Marks a trace as closed, preventing any further span ingestion for that trace. Once closed, subsequent calls to `/spans-bulk` or `/v1/traces` that include spans for this trace will have those spans rejected.", "parameters": [ { "name": "trace_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The trace ID to close.", "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } ], "responses": { "201": { "description": "Trace successfully closed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "closure": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "integer" }, "trace_id": { "type": "string" }, "status": { "type": "string", "enum": [ "closed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "examples": { "closed": { "summary": "Trace closed", "value": { "success": true, "closure": { "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": 1, "trace_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "status": "closed", "created_at": "2026-06-06T18:00:00Z", "updated_at": "2026-06-06T18:00:00Z" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Trace is already closed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Trace already closed" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v2/env-vars": { "get": { "tags": [ "env-vars" ], "summary": "List Workspace Env Vars", "operationId": "list_workspace_env_vars", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workspace_env_vars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "env-vars" ], "summary": "Create Workspace Env Var", "operationId": "create_workspace_env_var", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Environment variable name. Must start with a letter or underscore and contain only letters, digits, and underscores." }, "value": { "type": "string", "maxLength": 8192, "description": "Value to store. May be empty to create a placeholder that the user will fill in later." } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workspace_env_var": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "409": { "description": "An environment variable with that key already exists in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/env-vars/{var_id}": { "patch": { "tags": [ "env-vars" ], "summary": "Update Workspace Env Var", "operationId": "update_workspace_env_var", "parameters": [ { "name": "var_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "New value for the environment variable. Must be non-empty." } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "workspace_env_var": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Workspace env var not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "env-vars" ], "summary": "Delete Workspace Env Var", "operationId": "delete_workspace_env_var", "parameters": [ { "name": "var_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Workspace env var not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/tool-registry/{identifier}/env-vars": { "get": { "tags": [ "env-vars", "tool-registry" ], "summary": "List Tool Env Vars", "operationId": "list_tool_env_vars", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Tool ID (numeric) or name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_env_vars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "post": { "tags": [ "env-vars", "tool-registry" ], "summary": "Create Tool Env Var", "operationId": "create_tool_env_var", "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": [ "key" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "description": "Environment variable name. Must start with a letter or underscore and contain only letters, digits, and underscores." }, "value": { "type": "string", "maxLength": 8192, "description": "Value to store. May be empty to create a placeholder that the user will fill in later." } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_env_var": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "409": { "description": "An environment variable with that key already exists on this tool.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/tool-registry/{identifier}/env-vars/{var_id}": { "patch": { "tags": [ "env-vars", "tool-registry" ], "summary": "Update Tool Env Var", "operationId": "update_tool_env_var", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Tool ID (numeric) or name" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "New value for the environment variable. Must be non-empty." } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tool_env_var": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "value_suffix": { "type": "string", "nullable": true, "description": "Last 4 characters of the stored value. Null or empty when the value is empty." }, "is_empty": { "type": "boolean", "description": "True when the value has not been set yet (placeholder created by the AI assistant)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer", "description": "Present on workspace-scoped env vars." }, "tool_registry_id": { "type": "integer", "description": "Present on tool-scoped env vars." } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Tool or env var not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "env-vars", "tool-registry" ], "summary": "Delete Tool Env Var", "operationId": "delete_tool_env_var", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "Tool ID (numeric) or name" } }, { "name": "var_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Tool or env var not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/public/v2/requests/analytics/custom-analytics": { "post": { "summary": "Request Analytics Custom Analytics", "operationId": "getRequestAnalyticsCustomAnalytics", "tags": [ "tracking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestAnalyticsCustomAnalyticsQuery" }, "examples": { "cost_by_model": { "summary": "Cost breakdown by model", "value": { "filter_group": { "logic": "AND", "filters": [ { "field": "request_start_time", "operator": "between", "value": [ "2025-06-01T00:00:00Z", "2025-06-08T00:00:00Z" ] } ] }, "customCharts": [ { "id": "cost_by_model", "title": "Cost by Model", "chartType": "bar", "metric": "sum", "metricField": "cost", "groupByField": "engine", "limit": 10 } ] } }, "requests_over_time": { "summary": "Request volume over time", "value": { "customCharts": [ { "id": "requests_over_time", "title": "Requests Over Time", "chartType": "line", "metric": "count", "timeSeries": true } ] } }, "multi_series": { "summary": "Input vs output tokens over time", "value": { "customCharts": [ { "id": "token_breakdown", "title": "Token Usage", "chartType": "area", "timeSeries": true, "series": [ { "key": "input", "label": "Input Tokens", "metric": "sum", "metricField": "input_tokens" }, { "key": "output", "label": "Output Tokens", "metric": "sum", "metricField": "output_tokens" } ], "derivedInsights": [ { "label": "Input/Output Ratio", "numeratorSeriesKey": "input", "denominatorSeriesKey": "output" } ] } ] } }, "p95_latency_by_metadata": { "summary": "p95 latency broken down by a metadata key", "value": { "customCharts": [ { "id": "latency_by_env", "title": "p95 Latency by Environment", "chartType": "bar", "metric": "percentile", "percentile": 95, "metricField": "latency_ms", "groupByMetadataKey": "environment" } ] } } } } } }, "responses": { "200": { "description": "Custom chart results in the order requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestAnalyticsCustomAnalyticsResponse" }, "examples": { "cost_by_model": { "summary": "Cost by model result", "value": { "success": true, "customCharts": [ { "id": "cost_by_model", "title": "Cost by Model", "chartType": "bar", "series": [ { "key": "value", "label": "Cost", "unit": "currency" } ], "data": [ { "label": "gpt-4o", "value": 8.42 }, { "label": "claude-sonnet-4-6", "value": 3.91 } ] } ] } } } } } }, "400": { "description": "Invalid chart spec or unsupported filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "Evaluation": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the evaluation" }, "name": { "type": "string", "description": "Name of the evaluation" }, "comment": { "type": "string", "nullable": true, "description": "Optional comment or description for the evaluation" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the evaluation was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the evaluation was last updated" }, "workspace_id": { "type": "integer", "description": "ID of the workspace this evaluation belongs to" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of the folder containing this evaluation" }, "user_id": { "type": "integer", "nullable": true, "description": "ID of the user who created this evaluation" }, "dataset_id": { "type": "integer", "nullable": true, "description": "ID of the dataset associated with this evaluation" }, "is_blueprint": { "type": "boolean", "description": "Whether this is a blueprint (pipeline definition) or a batch run" }, "tags": { "type": "object", "nullable": true, "description": "Tags associated with this evaluation" }, "deleted": { "type": "boolean", "description": "Whether this evaluation has been deleted" }, "parent_report_id": { "type": "integer", "nullable": true, "description": "ID of the parent blueprint (set for batch runs)" }, "score_configuration": { "type": "object", "nullable": true, "description": "Custom scoring configuration for this evaluation" }, "runs": { "type": "array", "description": "Batch runs for this evaluation. Only present when include_runs=true.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the run" }, "name": { "type": "string", "description": "Name of the run" }, "comment": { "type": "string", "nullable": true, "description": "Optional comment or description" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the run was last updated" }, "workspace_id": { "type": "integer", "description": "ID of the workspace" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of the folder" }, "user_id": { "type": "integer", "nullable": true, "description": "ID of the user who created this run" }, "dataset_id": { "type": "integer", "nullable": true, "description": "ID of the dataset" }, "is_blueprint": { "type": "boolean", "description": "Whether this is a blueprint" }, "tags": { "type": "object", "nullable": true, "description": "Tags associated with this run" }, "deleted": { "type": "boolean", "description": "Whether this run has been deleted" }, "parent_report_id": { "type": "integer", "nullable": true, "description": "ID of the parent blueprint" }, "score_configuration": { "type": "object", "nullable": true, "description": "Custom scoring configuration" }, "score": { "type": "object", "nullable": true, "description": "Computed score for this run" }, "score_matrix": { "type": "array", "nullable": true, "description": "Matrix of scores across evaluation columns" }, "score_calculation_error": { "type": "string", "nullable": true, "description": "Error message if score calculation failed" }, "status": { "type": "string", "enum": [ "RUNNING", "COMPLETED" ], "description": "Current status of the batch run" }, "stats": { "type": "object", "description": "Run statistics", "properties": { "status_counts": { "type": "object", "description": "Count of cells by status" } } } } } }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this evaluation." } }, "required": [ "id", "name", "workspace_id" ] }, "GetSnippetUsageResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "snippet_name": { "type": "string", "description": "The name of the snippet prompt template" }, "snippet_usage": { "type": "array", "items": { "type": "object", "properties": { "prompt_registry_id": { "type": "integer", "description": "The ID of the prompt that uses this snippet" }, "prompt_name": { "type": "string", "description": "The name of the prompt that uses this snippet" }, "version_numbers": { "type": "array", "items": { "type": "integer" }, "description": "List of version numbers that use this snippet" } } }, "description": "List of prompts using this snippet" }, "total_prompts_using_snippet": { "type": "integer", "description": "Total number of prompts using this snippet" }, "label_usage": { "type": "array", "items": { "type": "object", "properties": { "prompt_registry_id": { "type": "integer", "description": "The ID of the prompt with a label using this snippet" }, "prompt_name": { "type": "string", "description": "The name of the prompt with a label using this snippet" }, "label_name": { "type": "string", "description": "The name of the label using this snippet" } } }, "description": "List of labels using this snippet" }, "total_labels_using_snippet": { "type": "integer", "description": "Total number of labels using this snippet" } }, "title": "GetSnippetUsageResponse" }, "RunWorkflow": { "type": "object", "properties": { "workflow_label_name": { "type": "string", "nullable": true, "description": "Specify a workflow label name to run a specific labeled version." }, "workflow_version_number": { "type": "integer", "nullable": true, "description": "Specify a workflow version number to run a specific version." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "A dictionary of metadata key-value pairs." }, "input_variables": { "type": "object", "additionalProperties": true, "default": {}, "description": "A dictionary of input variables required by the workflow." }, "return_all_outputs": { "type": "boolean", "default": false, "description": "If set to `true`, all outputs from the workflow execution will be returned." }, "callback_url": { "type": "string", "format": "uri", "nullable": true, "description": "HTTP URL where execution results are posted asynchronously. When provided, the API returns 202 Accepted immediately." } }, "required": [], "description": "Parameters to run a workflow by label, version number, or latest version. workflow_label_name and workflow_version_number are mutually exclusive." }, "RunWorkflowResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful." }, "message": { "type": "string", "description": "A message describing the result." }, "warning": { "type": "string", "nullable": true, "description": "Warning about missing or unused input variables, if any." }, "workflow_version_execution_id": { "type": "integer", "description": "The ID of the created workflow execution." } }, "required": [ "success", "message", "workflow_version_execution_id" ], "description": "Response after initiating a workflow execution." }, "WorkflowNode": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique name for the node within this workflow." }, "node_type": { "type": "string", "description": "The type of node. Common types include VARIABLE, CODE_EXECUTION, PROMPT_TEMPLATE, ENDPOINT, COMPARE, CONTAINS, LLM_ASSERTION, AI_DATA_EXTRACTION, CODING_AGENT. See Node & Column Types documentation for the complete list.", "examples": [ "VARIABLE", "PROMPT_TEMPLATE", "CODE_EXECUTION" ] }, "configuration": { "type": "object", "description": "Node-specific configuration.", "additionalProperties": true }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "Names of nodes or input variables this node depends on." }, "is_output_node": { "type": "boolean", "description": "Whether this node is an output node." } }, "required": [ "name", "node_type", "configuration", "is_output_node" ], "example": { "name": "greeting", "node_type": "VARIABLE", "is_output_node": true, "configuration": { "value": { "type": "string", "value": "Hello, World!" } }, "dependencies": [] } }, "EdgeConditional": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Order of evaluation." }, "operator": { "type": "string", "enum": [ "=", "!=", "<", ">", "<=", ">=", "in", "not_in", "is_null", "is_not_null" ], "description": "Comparison operator." }, "left_config": { "type": "object", "description": "Left side of comparison. Can be static_value or source." }, "right_config": { "type": "object", "description": "Right side of comparison. Can be static_value or source." } }, "required": [ "position", "operator", "left_config", "right_config" ] }, "Edge": { "type": "object", "properties": { "source_node_name": { "type": "string", "description": "The source node name." }, "target_node_name": { "type": "string", "description": "The target node name." }, "is_and": { "type": "boolean", "description": "Whether multiple conditionals use AND logic (true) or OR logic (false)." }, "conditionals": { "type": "array", "items": { "$ref": "#/components/schemas/EdgeConditional" }, "minItems": 1, "description": "At least one conditional." } }, "required": [ "source_node_name", "target_node_name", "is_and", "conditionals" ] }, "CreateWorkflow": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "The name for a new workflow. If not provided, a name will be auto-generated." }, "workflow_id": { "type": "integer", "nullable": true, "description": "The ID of an existing workflow to create a new version for." }, "workflow_name": { "type": "string", "nullable": true, "description": "The name of an existing workflow to create a new version for." }, "folder_id": { "type": "integer", "nullable": true, "description": "The folder ID to place the workflow in." }, "commit_message": { "type": "string", "nullable": true, "description": "A message describing the changes in this version." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" }, "description": "Complete list of workflow nodes. At least one node must be marked is_output_node=true." }, "required_input_variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A mapping of variable names to their types." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" }, "nullable": true, "description": "Conditional edges between nodes." }, "release_labels": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Labels to attach to this version." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." } }, "required": [ "nodes" ], "description": "Request body for creating a new workflow or a new version of an existing workflow. Use name for a new workflow, or workflow_id/workflow_name to version an existing workflow." }, "NodeUpdate": { "type": "object", "properties": { "node_type": { "type": "string", "nullable": true, "description": "The node type (required for new nodes)." }, "configuration": { "type": "object", "nullable": true, "description": "Node configuration to merge." }, "dependencies": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Dependencies to replace." }, "is_output_node": { "type": "boolean", "nullable": true, "description": "Whether this is an output node." } }, "description": "Partial update for a single node." }, "PatchWorkflow": { "type": "object", "properties": { "base_version": { "type": "integer", "nullable": true, "description": "The version number to base changes on. Defaults to the latest version." }, "commit_message": { "type": "string", "nullable": true, "description": "A message describing the changes." }, "nodes": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/NodeUpdate" }, { "type": "null" } ] }, "nullable": true, "description": "Node updates keyed by node name. Provide an object to add/update a node, or null to remove a node. Node configuration is deep-merged; dependencies are replaced." }, "required_input_variables": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "If provided, replaces the input variables entirely." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" }, "nullable": true, "description": "If provided, replaces edges entirely. If omitted, existing edges are copied except edges that reference removed nodes." }, "release_labels": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Labels to move or attach to the newly created workflow version." } }, "description": "Request body for partially updating a workflow. The server fetches base_version (latest if omitted), merges node updates, and creates a new version." }, "CreateWorkflowResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful." }, "workflow_id": { "type": "integer", "description": "The ID of the workflow." }, "workflow_name": { "type": "string", "description": "The name of the workflow." }, "workflow_version_id": { "type": "integer", "description": "The ID of the created workflow version." }, "version_number": { "type": "integer", "description": "The version number." }, "base_version": { "type": "integer", "nullable": true, "description": "The base version this was created from (PATCH only)." }, "release_labels": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Labels attached to this version." }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "node_type": { "type": "string" }, "is_output_node": { "type": "boolean" } } }, "description": "Summary of nodes in the workflow." }, "required_input_variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Required input variables for the workflow." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings for the workflow." } }, "required": [ "success", "workflow_id", "workflow_name", "workflow_version_id", "version_number", "external_ids" ], "description": "Response after creating or patching a workflow." }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "default": false, "description": "Indicates that the request failed." }, "message": { "type": "string", "description": "Human-readable error message." }, "error": { "type": "string", "description": "Machine-readable or fallback error message." } }, "additionalProperties": true, "description": "Standard error response. Some legacy endpoints may return either message or error." }, "SkillCollectionErrorResponse": { "type": "object", "description": "Error response format returned by the public skill collection endpoints.", "properties": { "success": { "type": "boolean", "enum": [ false ], "description": "Indicates that the request failed." }, "message": { "type": "string", "description": "Error message explaining why the request failed." } }, "required": [ "success", "message" ] }, "SkillCollection": { "type": "object", "description": "A skill collection container in the public API.", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "integer" }, "folder_id": { "type": "integer", "nullable": true }, "root_path": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "is_deleted": { "type": "boolean" }, "created_by": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "integer", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this skill collection." } } }, "SkillCollectionVersion": { "type": "object", "description": "A saved version of a skill collection.", "properties": { "id": { "type": "string", "format": "uuid" }, "skill_collection_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "integer" }, "number": { "type": "integer" }, "root_path_at_version": { "type": "string" }, "provider": { "type": "string", "nullable": true }, "file_paths": { "type": "array", "items": { "type": "string" } }, "commit_message": { "type": "string", "nullable": true }, "release_label": { "type": "string", "nullable": true }, "archived": { "type": "boolean" }, "created_by": { "type": "integer", "nullable": true }, "user_email": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "InitialFileUpdate": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "content": { "type": "string", "default": "" } } }, "FileUpdate": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "content": { "type": "string", "default": "" } } }, "FileMove": { "type": "object", "required": [ "old_path", "new_path" ], "properties": { "old_path": { "type": "string" }, "new_path": { "type": "string" } } }, "CreateSkillCollectionRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "folder_id": { "type": "integer", "nullable": true }, "provider": { "type": "string", "nullable": true }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/InitialFileUpdate" }, "default": [] }, "commit_message": { "type": "string", "nullable": true }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." } } }, "CreateSkillCollectionMultipartRequest": { "type": "object", "properties": { "metadata": { "type": "string", "description": "JSON string metadata containing `name`, `folder_id`, `provider`, `files`, and `commit_message`." }, "json": { "type": "string", "description": "Alternative metadata JSON string." }, "archive": { "type": "string", "format": "binary", "description": "Optional ZIP archive upload." }, "zip": { "type": "string", "format": "binary", "description": "Optional ZIP archive upload alias." } } }, "UpdateSkillCollectionRequest": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } } }, "SaveSkillCollectionVersionRequest": { "type": "object", "properties": { "file_updates": { "type": "array", "items": { "$ref": "#/components/schemas/FileUpdate" }, "default": [] }, "moves": { "type": "array", "items": { "$ref": "#/components/schemas/FileMove" }, "default": [] }, "deletes": { "type": "array", "items": { "type": "string" }, "default": [] }, "commit_message": { "type": "string", "nullable": true }, "release_label": { "type": "string", "nullable": true } } }, "SaveSkillCollectionVersionMultipartRequest": { "type": "object", "properties": { "metadata": { "type": "string", "description": "JSON string metadata containing `moves`, `deletes`, `commit_message`, `release_label`, and `file_updates`." }, "json": { "type": "string", "description": "Alternative metadata JSON string." }, "archive": { "type": "string", "format": "binary", "description": "Optional ZIP archive upload." }, "zip": { "type": "string", "format": "binary", "description": "Optional ZIP archive upload alias." } } }, "ListSkillCollectionsResponse": { "type": "object", "required": [ "success", "skill_collections" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "skill_collections": { "type": "array", "items": { "$ref": "#/components/schemas/SkillCollection" } } } }, "GetSkillCollectionResponse": { "type": "object", "required": [ "success", "skill_collection", "files", "version" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "skill_collection": { "$ref": "#/components/schemas/SkillCollection" }, "files": { "type": "object", "additionalProperties": { "type": "string" } }, "version": { "oneOf": [ { "$ref": "#/components/schemas/SkillCollectionVersion" }, { "type": "null" } ] } } }, "CreateSkillCollectionResponse": { "type": "object", "required": [ "success", "skill_collection", "external_ids" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "skill_collection": { "$ref": "#/components/schemas/SkillCollection" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings for the skill collection." } } }, "UpdateSkillCollectionResponse": { "type": "object", "required": [ "success", "skill_collection" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "skill_collection": { "$ref": "#/components/schemas/SkillCollection" } } }, "SaveSkillCollectionVersionResponse": { "type": "object", "required": [ "success", "version" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "version": { "$ref": "#/components/schemas/SkillCollectionVersion" } } }, "Base": { "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "title": "Page", "default": 1 }, "per_page": { "type": "integer", "exclusiveMinimum": 0, "title": "Per Page", "default": 30 } }, "type": "object", "title": "Base" }, "Function": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description", "default": "" }, "strict": { "type": "boolean", "title": "Strict", "default": false, "description": "Whether to enable strict schema validation for the function parameters." }, "parameters": { "type": "object", "title": "Parameters", "default": { "type": "object", "properties": {} } } }, "type": "object", "required": [ "name" ], "title": "Function" }, "FunctionCall": { "properties": { "name": { "type": "string", "title": "Name" }, "arguments": { "type": "string", "title": "Arguments" } }, "type": "object", "required": [ "name", "arguments" ], "title": "FunctionCall" }, "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" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Model": { "title": "Model", "type": "object", "properties": { "provider": { "title": "Provider", "type": "string", "description": "The LLM provider (e.g. openai, anthropic, google, openai.azure, vertexai, mistral, cohere, amazon.bedrock, huggingface)." }, "model_config_display_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "default": null, "title": "Model Config Display Name", "description": "Optional display name for the model configuration." }, "base_model": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "default": null, "title": "Base Model", "description": "The base model name (e.g. for fine-tuned models)." }, "name": { "title": "Name", "type": "string", "description": "The model name (e.g. gpt-4o, claude-sonnet-4-20250514)." }, "parameters": { "title": "Parameters", "default": {}, "type": "object", "description": "Model parameters (e.g. temperature, max_tokens, top_p)." }, "display_params": { "title": "Display Params", "default": {}, "type": "object", "description": "Display-friendly parameter values shown in the UI." }, "api_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Type", "description": "The API type (e.g. chat.completions, responses, images). Used to select the correct API endpoint for the provider." } }, "required": [ "provider", "name" ] }, "Metadata": { "title": "Metadata", "type": "object", "additionalProperties": true, "properties": { "model": { "anyOf": [ { "$ref": "#/components/schemas/Model" }, { "type": "null" } ], "default": null, "title": "Model" } }, "description": "Metadata associated with the prompt blueprint. Supports additional custom fields beyond the model field." }, "GetPromptTemplate": { "properties": { "version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Version" }, "workspace_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workspace Id" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "openai", "anthropic" ] }, { "type": "null" } ], "title": "Provider" }, "input_variables": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Input Variables" }, "metadata_filters": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata Filters", "description": "Optional dictionary of key values used for A/B release labels." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modal", "description": "Optional model name used for returning default parameters with llm_kwargs." }, "model_parameter_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Model Parameter Overrides", "description": "Optional dictionary of model parameter overrides to use with the prompt template. This will override the parameters at runtime for the specified model and will try to make sure the model supports these parameters. For example, if you supply `maxOutputTokens` for OpenAI, it will be converted to `max_completion_tokens`." } }, "type": "object", "title": "GetPromptTemplate" }, "CompletionPrompt": { "additionalProperties": true, "properties": { "content": { "items": { "discriminator": { "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "title": "Content", "type": "array" }, "input_variables": { "default": [], "items": { "type": "string" }, "title": "Input Variables", "type": "array" }, "template_format": { "default": "f-string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "type": "string" }, "type": { "const": "completion", "default": "completion", "enum": [ "completion" ], "title": "Type", "type": "string" } }, "required": [ "content" ], "title": "Completion Template", "type": "object" }, "FileAnnotation": { "properties": { "type": { "const": "file_citation", "title": "Type", "type": "string" }, "index": { "type": "integer", "title": "Index" }, "file_id": { "type": "string", "title": "File Id" }, "filename": { "type": "string", "title": "Filename" } }, "type": "object", "required": [ "type", "index", "file_id", "filename" ], "title": "FileAnnotation" }, "WebAnnotation": { "properties": { "type": { "const": "url_citation", "title": "Type", "type": "string" }, "title": { "type": "string", "title": "Title" }, "url": { "type": "string", "title": "Url" }, "start_index": { "type": "integer", "title": "Start Index" }, "end_index": { "type": "integer", "title": "End Index" }, "cited_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cited Text" }, "encrypted_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Encrypted Index" } }, "type": "object", "required": [ "type", "title", "url", "start_index", "end_index" ], "title": "WebAnnotation" }, "MapAnnotation": { "properties": { "type": { "const": "map_citation", "title": "Type", "type": "string" }, "title": { "type": "string", "title": "Title" }, "url": { "type": "string", "title": "Url" }, "place_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Place Id" }, "start_index": { "type": "integer", "title": "Start Index" }, "end_index": { "type": "integer", "title": "End Index" }, "cited_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cited Text" } }, "type": "object", "required": [ "type", "title", "url", "start_index", "end_index" ], "title": "MapAnnotation" }, "ContainerFileAnnotation": { "properties": { "type": { "const": "container_file_citation", "title": "Type", "type": "string" }, "container_id": { "type": "string", "title": "Container Id" }, "start_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Start Index" }, "end_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "End Index" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" } }, "type": "object", "required": [ "type", "container_id" ], "title": "ContainerFileAnnotation" }, "TextContent": { "properties": { "type": { "const": "text", "default": "text", "enum": [ "text" ], "title": "Type", "type": "string" }, "text": { "title": "Text", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "annotations": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/WebAnnotation" }, { "$ref": "#/components/schemas/FileAnnotation" }, { "$ref": "#/components/schemas/MapAnnotation" }, { "$ref": "#/components/schemas/ContainerFileAnnotation" } ] }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Annotations", "description": "Citations and references within the text (web citations, file citations, map citations, container file citations)." }, "thought_signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thought Signature" } }, "required": [ "text" ], "title": "TextContent", "type": "object" }, "ThinkingContent": { "properties": { "signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signature" }, "type": { "const": "thinking", "default": "thinking", "enum": [ "thinking" ], "title": "Type", "type": "string" }, "thinking": { "title": "Thinking", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" } }, "required": [ "thinking" ], "title": "ThinkingContent", "type": "object" }, "ImageURL": { "properties": { "url": { "type": "string", "title": "Url" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" } }, "type": "object", "required": [ "url" ], "title": "ImageURL" }, "Media": { "properties": { "title": { "type": "string", "title": "Title", "default": "media", "description": "Title of the media" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "default": "image/jpeg", "description": "MIME type of the media. For example, image/png, image/jpeg" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" }, "format": { "type": "string", "enum": [ "base64", "url", "neither" ], "title": "Format", "default": "neither", "description": "Format of the media data." } }, "type": "object", "title": "Media" }, "ImageContent": { "properties": { "type": { "const": "image_url", "default": "image_url", "enum": [ "image_url" ], "title": "Type", "type": "string" }, "image_url": { "$ref": "#/components/schemas/ImageURL" }, "image_variable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Image Variable" } }, "required": [ "image_url" ], "title": "ImageContent", "type": "object" }, "MediaContent": { "properties": { "type": { "const": "media", "default": "media", "enum": [ "media" ], "title": "Type", "type": "string" }, "media": { "$ref": "#/components/schemas/Media" } }, "required": [ "media" ], "title": "MediaContent", "type": "object" }, "MediaVariable": { "properties": { "type": { "const": "media_variable", "default": "media_variable", "enum": [ "media_variable" ], "title": "Type", "type": "string" }, "name": { "type": "string", "title": "Name", "description": "Name of the media variable" } }, "required": [ "name" ], "title": "MediaVariable", "type": "object" }, "OutputMediaContent": { "description": "LLM-generated media output (e.g. from image generation tools).", "properties": { "type": { "const": "output_media", "default": "output_media", "enum": [ "output_media" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "url": { "type": "string", "title": "Url" }, "mime_type": { "type": "string", "default": "image/png", "title": "Mime Type" }, "media_type": { "enum": [ "image", "video", "audio" ], "default": "image", "title": "Media Type", "type": "string" }, "provider_metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "default": null, "title": "Provider Metadata" } }, "required": [ "url" ], "title": "OutputMediaContent", "type": "object" }, "CodeContent": { "description": "Code content block (e.g. from code execution tools).", "properties": { "type": { "const": "code", "default": "code", "enum": [ "code" ], "title": "Type", "type": "string" }, "code": { "type": "string", "title": "Code" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "container_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Container Id" } }, "required": [ "code" ], "title": "CodeContent", "type": "object" }, "ServerToolUseContent": { "description": "Server-side tool use block (e.g. web search, code execution).", "properties": { "type": { "const": "server_tool_use", "default": "server_tool_use", "enum": [ "server_tool_use" ], "title": "Type", "type": "string" }, "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "input": { "type": "object", "default": {}, "title": "Input" } }, "required": [ "id", "name" ], "title": "ServerToolUseContent", "type": "object" }, "WebSearchResult": { "properties": { "type": { "const": "web_search_result", "default": "web_search_result", "enum": [ "web_search_result" ], "title": "Type", "type": "string" }, "url": { "type": "string", "default": "", "title": "Url" }, "title": { "type": "string", "default": "", "title": "Title" }, "encrypted_content": { "type": "string", "default": "", "title": "Encrypted Content" }, "page_age": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Page Age" } }, "title": "WebSearchResult", "type": "object" }, "WebSearchToolResultContent": { "description": "Results from a web search tool invocation.", "properties": { "type": { "const": "web_search_tool_result", "default": "web_search_tool_result", "enum": [ "web_search_tool_result" ], "title": "Type", "type": "string" }, "tool_use_id": { "type": "string", "title": "Tool Use Id" }, "content": { "items": { "$ref": "#/components/schemas/WebSearchResult" }, "type": "array", "default": [], "title": "Content" } }, "required": [ "tool_use_id" ], "title": "WebSearchToolResultContent", "type": "object" }, "CodeExecutionResultContent": { "description": "Result from a code execution tool.", "properties": { "type": { "const": "code_execution_result", "default": "code_execution_result", "enum": [ "code_execution_result" ], "title": "Type", "type": "string" }, "output": { "type": "string", "title": "Output" }, "outcome": { "type": "string", "default": "OUTCOME_OK", "title": "Outcome" } }, "required": [ "output" ], "title": "CodeExecutionResultContent", "type": "object" }, "McpListToolsContent": { "description": "MCP list tools response block.", "properties": { "type": { "const": "mcp_list_tools", "default": "mcp_list_tools", "enum": [ "mcp_list_tools" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "server_label": { "type": "string", "default": "", "title": "Server Label" }, "tools": { "items": { "type": "object" }, "type": "array", "default": [], "title": "Tools" }, "error": { "anyOf": [ { "type": "string" }, { "type": "object" }, { "type": "null" } ], "default": null, "title": "Error" } }, "title": "McpListToolsContent", "type": "object" }, "McpCallContent": { "description": "MCP tool call block.", "properties": { "type": { "const": "mcp_call", "default": "mcp_call", "enum": [ "mcp_call" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "name": { "type": "string", "default": "", "title": "Name" }, "server_label": { "type": "string", "default": "", "title": "Server Label" }, "arguments": { "type": "string", "default": "", "title": "Arguments" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Output" }, "error": { "anyOf": [ { "type": "string" }, { "type": "object" }, { "type": "null" } ], "default": null, "title": "Error" }, "approval_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Request Id" } }, "title": "McpCallContent", "type": "object" }, "McpApprovalRequestContent": { "description": "MCP tool approval request block.", "properties": { "type": { "const": "mcp_approval_request", "default": "mcp_approval_request", "enum": [ "mcp_approval_request" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "name": { "type": "string", "default": "", "title": "Name" }, "arguments": { "type": "string", "default": "", "title": "Arguments" }, "server_label": { "type": "string", "default": "", "title": "Server Label" } }, "title": "McpApprovalRequestContent", "type": "object" }, "McpApprovalResponseContent": { "description": "MCP tool approval response block.", "properties": { "type": { "const": "mcp_approval_response", "default": "mcp_approval_response", "enum": [ "mcp_approval_response" ], "title": "Type", "type": "string" }, "approval_request_id": { "type": "string", "title": "Approval Request Id" }, "approve": { "type": "boolean", "title": "Approve" } }, "required": [ "approval_request_id", "approve" ], "title": "McpApprovalResponseContent", "type": "object" }, "BashCodeExecutionToolResultContent": { "description": "Result from bash code execution tool.", "properties": { "type": { "const": "bash_code_execution_tool_result", "default": "bash_code_execution_tool_result", "enum": [ "bash_code_execution_tool_result" ], "title": "Type", "type": "string" }, "tool_use_id": { "type": "string", "title": "Tool Use Id" }, "content": { "type": "object", "default": {}, "title": "Content" } }, "required": [ "tool_use_id" ], "title": "BashCodeExecutionToolResultContent", "type": "object" }, "TextEditorCodeExecutionToolResultContent": { "description": "Result from text editor code execution tool.", "properties": { "type": { "const": "text_editor_code_execution_tool_result", "default": "text_editor_code_execution_tool_result", "enum": [ "text_editor_code_execution_tool_result" ], "title": "Type", "type": "string" }, "tool_use_id": { "type": "string", "title": "Tool Use Id" }, "content": { "type": "object", "default": {}, "title": "Content" } }, "required": [ "tool_use_id" ], "title": "TextEditorCodeExecutionToolResultContent", "type": "object" }, "ShellCallContent": { "description": "Shell tool call block.", "properties": { "type": { "const": "shell_call", "default": "shell_call", "enum": [ "shell_call" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "action": { "type": "object", "default": {}, "title": "Action" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "title": "ShellCallContent", "type": "object" }, "ShellCallOutputContent": { "description": "Shell tool output block.", "properties": { "type": { "const": "shell_call_output", "default": "shell_call_output", "enum": [ "shell_call_output" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "output": { "items": { "type": "object" }, "type": "array", "default": [], "title": "Output" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "title": "ShellCallOutputContent", "type": "object" }, "ApplyPatchCallContent": { "description": "Apply patch tool call block.", "properties": { "type": { "const": "apply_patch_call", "default": "apply_patch_call", "enum": [ "apply_patch_call" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "operation": { "type": "object", "default": {}, "title": "Operation" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "title": "ApplyPatchCallContent", "type": "object" }, "ApplyPatchCallOutputContent": { "description": "Apply patch tool output block.", "properties": { "type": { "const": "apply_patch_call_output", "default": "apply_patch_call_output", "enum": [ "apply_patch_call_output" ], "title": "Type", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "output": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Output" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "title": "ApplyPatchCallOutputContent", "type": "object" }, "BuiltInTool": { "description": "A provider-native built-in tool (e.g. web search, code interpreter, bash).", "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "provider": { "type": "string", "title": "Provider" }, "type": { "enum": [ "web_search", "file_search", "code_interpreter", "image_generation", "google_maps", "url_context", "mcp", "bash", "shell", "apply_patch", "text_editor" ], "title": "Type", "type": "string" }, "config": { "type": "object", "title": "Config", "description": "Provider-specific tool configuration. Structure varies by provider and tool type." } }, "required": [ "id", "name", "description", "provider", "type", "config" ], "title": "BuiltInTool", "type": "object" }, "SystemMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array", "title": "Content" }, "role": { "const": "system", "title": "Role", "default": "system" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "content" ], "title": "SystemMessage" }, "UserMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array", "title": "Content" }, "role": { "const": "user", "title": "Role", "default": "user" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "content" ], "title": "UserMessage" }, "AssistantMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "anyOf": [ { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "role": { "const": "assistant", "title": "Role", "default": "assistant" }, "function_call": { "anyOf": [ { "$ref": "#/components/schemas/FunctionCall" }, { "type": "null" } ], "title": "Function Call", "deprecated": true, "description": "This field is deprecated. Please use `tool_calls` field to specify tool calls." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "tool_calls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ToolCall" }, "type": "array" }, { "type": "null" } ], "title": "Tool Calls" } }, "type": "object", "title": "AssistantMessage" }, "FunctionMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "anyOf": [ { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array" }, { "type": "null" } ], "title": "Content" }, "role": { "const": "function", "title": "Role", "default": "function" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "FunctionMessage" }, "DeveloperMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array", "title": "Content" }, "role": { "const": "developer", "title": "Role", "default": "developer" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "content" ], "title": "DeveloperMessage" }, "MessageFunctionCall": { "properties": { "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "MessageFunctionCall" }, "ChatPrompt": { "properties": { "messages": { "items": { "discriminator": { "mapping": { "assistant": "#/components/schemas/AssistantMessage", "function": "#/components/schemas/FunctionMessage", "placeholder": "#/components/schemas/PlaceholderMessage", "system": "#/components/schemas/SystemMessage", "tool": "#/components/schemas/ToolMessage", "user": "#/components/schemas/UserMessage", "developer": "#/components/schemas/DeveloperMessage" }, "propertyName": "role" }, "oneOf": [ { "$ref": "#/components/schemas/SystemMessage" }, { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/AssistantMessage" }, { "$ref": "#/components/schemas/FunctionMessage" }, { "$ref": "#/components/schemas/ToolMessage" }, { "$ref": "#/components/schemas/PlaceholderMessage" }, { "$ref": "#/components/schemas/DeveloperMessage" } ] }, "title": "Messages", "type": "array" }, "functions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Function" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Functions" }, "tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Tool" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tools" }, "function_call": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/MessageFunctionCall" }, { "type": "null" } ], "default": null, "title": "Function Call" }, "tool_choice": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ChatToolChoice" }, { "type": "null" } ], "default": null, "title": "Tool Choice" }, "type": { "const": "chat", "default": "chat", "enum": [ "chat" ], "title": "Type", "type": "string" }, "input_variables": { "default": [], "items": { "type": "string" }, "title": "Input Variables", "type": "array" } }, "required": [ "messages" ], "title": "Chat Template", "type": "object" }, "GetPromptTemplateResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "prompt_name": { "type": "string", "title": "Prompt Name" }, "prompt_template": { "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } } }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ] }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commit Message" }, "llm_kwargs": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Llm Kwargs", "description": "When you optionally specify `provider` in the body, `llm_kwargs` will be returned for that specific provider and you can pass these kwargs to the provider's API directly. **Important:** This object's structure is provider-specific and may change without notice as LLM providers update their APIs. For stable, provider-agnostic prompt data, use `prompt_template` instead." }, "version": { "type": "integer", "title": "Version" } }, "type": "object", "required": [ "id", "prompt_name", "prompt_template" ], "title": "GetPromptTemplateResponse" }, "SnippetReference": { "properties": { "prompt_name": { "type": "string", "title": "Prompt Name", "description": "The name of the snippet prompt template." }, "version": { "type": "integer", "title": "Version", "description": "The version number of the snippet used." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "The release label of the snippet, if applicable." } }, "type": "object", "required": [ "prompt_name", "version" ], "title": "SnippetReference" }, "GetPromptTemplateRawResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "id": { "type": "integer", "title": "Id", "description": "The prompt template ID." }, "prompt_name": { "type": "string", "title": "Prompt Name", "description": "The name of the prompt template." }, "version": { "type": "integer", "title": "Version", "description": "The version number of the prompt template." }, "workspace_id": { "type": "integer", "title": "Workspace Id", "description": "The workspace this prompt template belongs to." }, "prompt_template": { "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "description": "The prompt template content. When resolve_snippets is true (default), snippets are expanded. When false, raw @@@snippet@@@ references are preserved.", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } } }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ], "description": "Model configuration including provider, model name, and parameters." }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commit Message", "description": "The commit message for this version." }, "tags": { "type": "array", "items": { "type": "string" }, "title": "Tags", "description": "Tags associated with the prompt template." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp when this version was created." }, "snippets": { "type": "array", "items": { "$ref": "#/components/schemas/SnippetReference" }, "title": "Snippets", "description": "List of snippet references used in this template." }, "llm_kwargs": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "LLM Kwargs", "description": "Provider-specific LLM arguments. Only present when include_llm_kwargs=true. Structure is provider-specific and may change without notice." } }, "type": "object", "required": [ "success", "id", "prompt_name", "version", "workspace_id", "prompt_template", "snippets" ], "title": "GetPromptTemplateRawResponse" }, "GetPromptTemplateLabelResponse": { "properties": { "release_labels": { "type": "array", "items": { "type": "object", "properties": { "prompt_version_id": { "type": "integer" }, "prompt_version_number": { "type": "integer" }, "release_label": { "type": "string" }, "release_label_id": { "type": "integer" } }, "required": [ "prompt_version_id", "prompt_version_number", "release_label", "release_label_id" ] }, "title": "Release Labels" } }, "type": "object", "required": [ "release_labels" ], "title": "GetPromptTemplateLabelResponse" }, "BasePromptTemplate": { "properties": { "prompt_name": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Prompt Name", "description": "The unique prompt name within the workspace. 1-512 characters." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "default": [], "description": "Tags to attach to the prompt registry entry." }, "folder_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Folder Id", "description": "The ID of the folder to publish the prompt template into. If omitted, the prompt is created at the workspace root. Use Resolve Folder ID by Path to look up an ID from a path, or Create Folder to make one." }, "workspace_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Workspace Id", "description": "Optional workspace override; defaults to the workspace associated with the API key." } }, "type": "object", "required": [ "prompt_name" ], "title": "BasePromptTemplate" }, "PromptVersion": { "properties": { "prompt_template": { "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } }, "description": "The prompt content, either chat or completion." }, "commit_message": { "anyOf": [ { "type": "string", "maxLength": 72 }, { "type": "null" } ], "title": "Commit Message", "description": "Message describing the changes in this version. Maximum 72 characters." }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ], "description": "Metadata to attach to the prompt version." } }, "type": "object", "required": [ "prompt_template" ], "title": "PromptVersion" }, "PatchPromptTemplateVersion": { "properties": { "version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Version", "description": "The base version number to patch from. Mutually exclusive with `label`. If neither is provided, the latest version is used." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "The release label identifying the base version to patch from (e.g. 'prod', 'staging'). Mutually exclusive with `version`." }, "messages": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Index-based patch. Keys are string indices (e.g. \"0\", \"1\"), values are the replacement message objects." }, { "type": "array", "items": {}, "description": "Full replacement. Replaces all messages." }, { "type": "null" } ], "title": "Messages", "description": "Patch for chat template messages. Object keys are message indexes for index-based patching; arrays replace all messages." }, "tools": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "null" } ], "title": "Tools", "description": "Patch for tools. Object for index-based patching, array for full replacement, null to remove. Chat templates only." }, "functions": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "null" } ], "title": "Functions", "description": "Patch for functions. Object for index-based patching, array for full replacement, null to remove. Chat templates only." }, "function_call": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Function Call", "description": "Replace the function_call setting. Set to null to remove. Chat templates only." }, "tool_choice": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Tool Choice", "description": "Replace the tool_choice setting. Set to null to remove. Chat templates only." }, "content": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "null" } ], "title": "Content", "description": "Patch for completion template content. Object for index-based patching, array for full replacement. Completion templates only." }, "model_parameters": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Model Parameters", "description": "Parameters to shallow-merge into existing model parameters. Existing keys not provided are preserved." }, "response_format": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Response Format", "description": "Convenience field to set response_format in model parameters. Cannot be used simultaneously with response_format inside model_parameters. Set to null to remove." }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commit Message", "description": "A message describing the changes in this version." }, "release_labels": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "title": "Release Labels", "description": "Release labels to create or move to the newly created version." } }, "type": "object", "title": "PatchPromptTemplateVersion", "description": "Request body for partially updating a prompt template by creating a new version from the latest, a specific version, or a release label." }, "CreatePromptTemplate": { "properties": { "prompt_template": { "$ref": "#/components/schemas/BasePromptTemplate", "description": "Template metadata, including prompt name, tags, folder, and workspace fields." }, "prompt_version": { "$ref": "#/components/schemas/PromptVersion", "description": "Version content and configuration." }, "release_labels": { "type": [ "array", "null" ], "items": { "type": "string" }, "title": "Release Labels", "description": "Release labels to create or move to the newly created version." }, "external_ids": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ExternalId" }, "title": "External Ids", "description": "Identifiers from other systems." } }, "type": "object", "required": [ "prompt_template", "prompt_version" ], "title": "CreatePromptTemplate" }, "CreatePromptTemplateResponse": { "properties": { "id": { "type": "integer", "title": "Id", "description": "The ID of the prompt template." }, "prompt_name": { "type": "string", "title": "Prompt Name", "description": "The name of the prompt template." }, "prompt_version_id": { "type": "integer", "title": "Prompt Version Id", "description": "The ID of the created prompt version." }, "version_number": { "type": "integer", "title": "Version Number", "description": "The version number of the prompt template." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags" }, "release_labels": { "type": [ "array", "null" ], "items": { "type": "string" }, "title": "Release Labels" }, "prompt_template": { "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } } }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ] }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commit Message" }, "external_ids": { "items": { "$ref": "#/components/schemas/ExternalId" }, "type": "array", "title": "External Ids", "description": "External ID mappings attached to the prompt template." } }, "type": "object", "required": [ "id", "prompt_name", "prompt_version_id", "version_number", "tags", "prompt_template", "external_ids" ], "title": "CreatePromptTemplateResponse" }, "ToolCall": { "properties": { "tool_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tool Id" }, "id": { "type": "string", "title": "Id" }, "type": { "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/FunctionCall" } }, "type": "object", "required": [ "id", "function" ], "title": "ToolCall" }, "ToolMessage": { "properties": { "input_variables": { "items": { "type": "string" }, "type": "array", "title": "Input Variables", "default": [] }, "template_format": { "type": "string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "default": "f-string" }, "content": { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array", "title": "Content" }, "role": { "const": "tool", "title": "Role", "default": "tool" }, "tool_call_id": { "type": "string", "title": "Tool Call Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "content", "tool_call_id" ], "title": "ToolMessage" }, "FunctionTool": { "description": "A custom function tool definition.", "properties": { "type": { "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/Function" } }, "type": "object", "required": [ "function" ], "title": "FunctionTool" }, "Tool": { "discriminator": { "propertyName": "type", "mapping": { "function": "#/components/schemas/FunctionTool", "web_search": "#/components/schemas/BuiltInTool", "file_search": "#/components/schemas/BuiltInTool", "code_interpreter": "#/components/schemas/BuiltInTool", "image_generation": "#/components/schemas/BuiltInTool", "google_maps": "#/components/schemas/BuiltInTool", "url_context": "#/components/schemas/BuiltInTool", "mcp": "#/components/schemas/BuiltInTool", "bash": "#/components/schemas/BuiltInTool", "shell": "#/components/schemas/BuiltInTool", "apply_patch": "#/components/schemas/BuiltInTool", "text_editor": "#/components/schemas/BuiltInTool" } }, "oneOf": [ { "$ref": "#/components/schemas/FunctionTool" }, { "$ref": "#/components/schemas/BuiltInTool" } ], "title": "Tool" }, "ChatToolChoice": { "properties": { "type": { "const": "function", "title": "Type", "default": "function" }, "function": { "$ref": "#/components/schemas/MessageFunctionCall" } }, "type": "object", "required": [ "function" ], "title": "ChatToolChoice" }, "ListPromptTemplates": { "properties": { "has_next": { "type": "boolean", "title": "Has Next" }, "has_prev": { "type": "boolean", "title": "Has Prev" }, "items": { "items": { "$ref": "#/components/schemas/ListPromptTemplateItem" }, "type": "array", "title": "Items" }, "next_num": { "type": "integer", "title": "Next Num" }, "prev_num": { "type": "integer", "title": "Prev Num" }, "page": { "type": "integer", "title": "Page" }, "pages": { "type": "integer", "title": "Pages" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "has_next", "has_prev", "items", "next_num", "prev_num", "page", "pages", "total" ], "title": "ListPromptTemplates" }, "PlaceholderMessage": { "properties": { "input_variables": { "default": [], "items": { "type": "string" }, "title": "Input Variables", "type": "array" }, "template_format": { "default": "f-string", "enum": [ "f-string", "jinja2" ], "title": "Template Format", "type": "string" }, "content": { "anyOf": [ { "items": { "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/TextContent", "thinking": "#/components/schemas/ThinkingContent", "code": "#/components/schemas/CodeContent", "image_url": "#/components/schemas/ImageContent", "media": "#/components/schemas/MediaContent", "media_variable": "#/components/schemas/MediaVariable", "output_media": "#/components/schemas/OutputMediaContent", "server_tool_use": "#/components/schemas/ServerToolUseContent", "web_search_tool_result": "#/components/schemas/WebSearchToolResultContent", "code_execution_result": "#/components/schemas/CodeExecutionResultContent", "mcp_list_tools": "#/components/schemas/McpListToolsContent", "mcp_call": "#/components/schemas/McpCallContent", "mcp_approval_request": "#/components/schemas/McpApprovalRequestContent", "mcp_approval_response": "#/components/schemas/McpApprovalResponseContent", "bash_code_execution_tool_result": "#/components/schemas/BashCodeExecutionToolResultContent", "text_editor_code_execution_tool_result": "#/components/schemas/TextEditorCodeExecutionToolResultContent", "shell_call": "#/components/schemas/ShellCallContent", "shell_call_output": "#/components/schemas/ShellCallOutputContent", "apply_patch_call": "#/components/schemas/ApplyPatchCallContent", "apply_patch_call_output": "#/components/schemas/ApplyPatchCallOutputContent" } }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ThinkingContent" }, { "$ref": "#/components/schemas/CodeContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/MediaContent" }, { "$ref": "#/components/schemas/MediaVariable" }, { "$ref": "#/components/schemas/OutputMediaContent" }, { "$ref": "#/components/schemas/ServerToolUseContent" }, { "$ref": "#/components/schemas/WebSearchToolResultContent" }, { "$ref": "#/components/schemas/CodeExecutionResultContent" }, { "$ref": "#/components/schemas/McpListToolsContent" }, { "$ref": "#/components/schemas/McpCallContent" }, { "$ref": "#/components/schemas/McpApprovalRequestContent" }, { "$ref": "#/components/schemas/McpApprovalResponseContent" }, { "$ref": "#/components/schemas/BashCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/TextEditorCodeExecutionToolResultContent" }, { "$ref": "#/components/schemas/ShellCallContent" }, { "$ref": "#/components/schemas/ShellCallOutputContent" }, { "$ref": "#/components/schemas/ApplyPatchCallContent" }, { "$ref": "#/components/schemas/ApplyPatchCallOutputContent" } ] }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Content" }, "raw_request_display_role": { "default": "", "title": "Raw Request Display Role", "type": "string" }, "role": { "const": "placeholder", "default": "placeholder", "enum": [ "placeholder" ], "title": "Role", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "PlaceholderMessage", "type": "object" }, "LogRequest": { "properties": { "provider": { "title": "Provider", "type": "string" }, "model": { "title": "Model", "type": "string" }, "input": { "discriminator": { "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Input" }, "output": { "discriminator": { "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Output" }, "request_start_time": { "format": "date-time", "title": "Request Start Time", "type": "string" }, "request_end_time": { "format": "date-time", "title": "Request End Time", "type": "string" }, "parameters": { "default": {}, "title": "Parameters", "type": "object", "description": "Model parameters including temperature, max_tokens, etc. Can also include structured output configuration via response_format.json_schema. See documentation for structured output examples." }, "tags": { "default": [], "items": { "maxLength": 512, "type": "string" }, "title": "Tags", "type": "array" }, "metadata": { "additionalProperties": { "type": "string" }, "default": {}, "title": "Metadata", "type": "object", "description": "Custom key-value pairs for tracking additional request information. Keys are limited to 1024 characters." }, "prompt_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompt Name" }, "prompt_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Prompt Id", "description": "The ID of the prompt template used for this request. This is useful for tracking which prompt was used in the request." }, "prompt_version_number": { "anyOf": [ { "exclusiveMinimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Prompt Version Number" }, "prompt_input_variables": { "default": {}, "title": "Prompt Input Variables", "type": "object" }, "input_tokens": { "default": 0, "minimum": 0, "title": "Input Tokens", "type": "integer" }, "output_tokens": { "default": 0, "minimum": 0, "title": "Output Tokens", "type": "integer" }, "price": { "default": 0, "minimum": 0, "title": "Price", "type": "number" }, "function_name": { "default": "", "title": "Function Name", "type": "string" }, "score": { "default": 0, "maximum": 100, "minimum": 0, "title": "Score", "type": "integer" }, "api_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Type" }, "status": { "type": "string", "enum": [ "SUCCESS", "WARNING", "ERROR" ], "default": "SUCCESS", "title": "Status", "description": "Request status.\n\n| Value | Description |\n|-------|-------------|\n| `SUCCESS` | Request completed successfully (default) |\n| `WARNING` | Request succeeded but had issues (e.g., retries, degraded response) |\n| `ERROR` | Request failed |" }, "error_type": { "anyOf": [ { "type": "string", "enum": [ "PROVIDER_TIMEOUT", "PROVIDER_QUOTA_LIMIT", "PROVIDER_RATE_LIMIT", "PROVIDER_PARTIAL_RESPONSE", "PROVIDER_AUTH_ERROR", "PROVIDER_ERROR", "TEMPLATE_RENDER_ERROR", "VARIABLE_MISSING_OR_EMPTY", "UNKNOWN_ERROR" ] }, { "type": "null" } ], "default": null, "title": "Error Type", "description": "Categorized error type.\n\n| Value | Description | Allowed Statuses |\n|-------|-------------|------------------|\n| `PROVIDER_RATE_LIMIT` | Rate limit hit on provider API | WARNING, ERROR |\n| `PROVIDER_QUOTA_LIMIT` | Account quota or spending limit exceeded | WARNING, ERROR |\n| `PROVIDER_PARTIAL_RESPONSE` | Provider returned a successful response, but the saved output may be incomplete, filtered, blocked, malformed, or otherwise partial | WARNING |\n| `VARIABLE_MISSING_OR_EMPTY` | Required template variable was missing or empty | WARNING |\n| `PROVIDER_TIMEOUT` | Request timed out | ERROR |\n| `PROVIDER_AUTH_ERROR` | Authentication failed with provider | ERROR |\n| `PROVIDER_ERROR` | General provider-side error | ERROR |\n| `TEMPLATE_RENDER_ERROR` | Failed to render prompt template | ERROR |\n| `UNKNOWN_ERROR` | Uncategorized error | WARNING, ERROR |" }, "error_message": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "default": null, "title": "Error Message", "description": "Detailed error message describing what went wrong. Maximum 1024 characters." } }, "required": [ "provider", "model", "input", "output", "request_start_time", "request_end_time" ], "title": "LogRequest", "type": "object", "description": "Request body for custom logging. Chat message content must be an array of content blocks, not a plain string." }, "LogRequestResponse": { "properties": { "id": { "title": "Id", "type": "integer" }, "prompt_version": { "$ref": "#/components/schemas/PromptVersion" }, "status": { "type": "string", "enum": [ "SUCCESS", "WARNING", "ERROR" ], "title": "Status", "description": "Request status indicating success, warning, or error." }, "error_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Type", "description": "Categorized error type if status is WARNING or ERROR." }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Detailed error message if status is WARNING or ERROR." } }, "required": [ "id", "prompt_version" ], "title": "LogRequestResponse", "type": "object" }, "BadRequestError": { "properties": { "success": { "const": false, "default": false, "enum": [ false ], "title": "Success", "type": "boolean" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "BadRequestError", "type": "object" }, "PromptBlueprint": { "properties": { "prompt_template": { "anyOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "description": "The prompt template. Either a CompletionPrompt (type: 'completion') or ChatPrompt (type: 'chat').", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } } }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Commit Message" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "provider_base_url_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "default": null, "title": "Provider Base Url Name", "description": "Name of the custom provider base URL configuration." }, "report_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Report Id" }, "inference_client_name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "default": null, "title": "Inference Client Name", "description": "Name of the inference client to use." }, "provider_id": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "default": null, "title": "Provider Id", "description": "ID of the provider configuration to use." } }, "type": "object", "required": [ "prompt_template" ], "title": "PromptBlueprint" }, "SpanKind": { "type": "string", "enum": [ "SpanKind.CLIENT", "SpanKind.CONSUMER", "SpanKind.INTERNAL", "SpanKind.PRODUCER", "SpanKind.SERVER" ], "title": "SpanKind" }, "StatusCode": { "type": "string", "enum": [ "StatusCode.ERROR", "StatusCode.OK", "StatusCode.UNSET" ], "title": "StatusCode" }, "SpanContext": { "type": "object", "properties": { "trace_id": { "type": "string", "title": "Trace ID" }, "span_id": { "type": "string", "title": "Span ID" }, "trace_state": { "type": "string", "title": "Trace State" } }, "required": [ "trace_id", "span_id", "trace_state" ], "title": "SpanContext" }, "SpanStatus": { "type": "object", "properties": { "status_code": { "$ref": "#/components/schemas/StatusCode" }, "description": { "type": "string", "title": "Description", "nullable": true } }, "required": [ "status_code" ], "title": "SpanStatus" }, "SpanResource": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Attributes" }, "schema_url": { "type": "string", "title": "Schema URL" } }, "required": [ "attributes", "schema_url" ], "title": "SpanResource" }, "Span": { "type": "object", "properties": { "name": { "type": "string", "title": "Name" }, "context": { "$ref": "#/components/schemas/SpanContext" }, "kind": { "$ref": "#/components/schemas/SpanKind" }, "parent_id": { "type": "string", "title": "Parent ID", "nullable": true }, "start_time": { "type": "integer", "title": "Start Time" }, "end_time": { "type": "integer", "title": "End Time" }, "status": { "$ref": "#/components/schemas/SpanStatus" }, "attributes": { "type": "object", "title": "Attributes" }, "events": { "type": "array", "items": { "type": "object" }, "title": "Events", "default": [] }, "links": { "type": "array", "items": { "type": "object" }, "title": "Links", "default": [] }, "resource": { "$ref": "#/components/schemas/SpanResource" }, "log_request": { "anyOf": [ { "$ref": "#/components/schemas/LogRequest" }, { "type": "null" } ], "title": "Log Request", "nullable": true, "description": "Optional request log to create alongside the span. If request times are omitted, they are inherited from the span start/end times." } }, "required": [ "name", "context", "kind", "start_time", "end_time", "status", "attributes", "resource" ], "title": "Span" }, "CreateSpansBulk": { "type": "object", "properties": { "spans": { "type": "array", "items": { "$ref": "#/components/schemas/Span" }, "title": "Spans" }, "close_after": { "type": "boolean", "default": false, "title": "Close After", "description": "When true, all trace IDs in this batch are marked as closed after the spans are persisted. Subsequent span writes for those traces will be rejected with a trace_closed rejection reason. Defaults to false." } }, "required": [ "spans" ], "title": "CreateSpansBulk", "description": "Create multiple observability spans in a single request. Each span may include log_request to create an associated request log." }, "CreateSpansBulkResponse": { "type": "object", "properties": { "success": { "type": "boolean", "title": "Success" }, "spans": { "type": "array", "items": { "type": "object" }, "title": "Spans" }, "request_logs": { "type": "array", "items": { "type": "object" }, "title": "Request Logs", "nullable": true }, "rejected_span_ids": { "type": "array", "items": { "type": "string" }, "title": "Rejected Span IDs", "description": "Span IDs that were dropped because they belong to a closed trace. Only present when one or more spans were rejected.", "nullable": true }, "rejected_trace_ids": { "type": "array", "items": { "type": "string" }, "title": "Rejected Trace IDs", "description": "Trace IDs that were closed and caused span rejections. Only present when one or more spans were rejected.", "nullable": true }, "rejection_reason": { "type": "string", "enum": [ "trace_closed" ], "title": "Rejection Reason", "description": "The reason spans were rejected. Currently only `trace_closed` is possible. Only present when one or more spans were rejected.", "nullable": true } }, "required": [ "success", "spans" ], "title": "CreateSpansBulkResponse" }, "Dataset": { "type": "object", "properties": { "id": { "type": "integer", "description": "Dataset ID" }, "dataset_group_id": { "type": "integer", "description": "Associated dataset group ID" }, "version_number": { "type": "integer", "description": "Version number of the dataset" }, "column_names": { "type": "array", "items": { "type": "string" }, "description": "Array of column names in the dataset" }, "filter_params": { "type": "object", "nullable": true, "description": "Filter parameters used to create the dataset" }, "is_deleted": { "type": "boolean", "description": "Whether the dataset is deleted" }, "user_id": { "type": "integer", "description": "ID of the user who created the dataset" }, "dataset_group": { "$ref": "#/components/schemas/DatasetGroup", "description": "Associated dataset group information" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this dataset group." } }, "required": [ "id", "dataset_group_id", "version_number", "column_names", "is_deleted", "user_id" ], "title": "Dataset" }, "DatasetGroup": { "type": "object", "properties": { "id": { "type": "integer", "description": "Dataset group ID" }, "name": { "type": "string", "description": "Dataset group name" }, "workspace_id": { "type": "integer", "description": "Associated workspace ID" }, "is_deleted": { "type": "boolean", "description": "Whether the dataset group is deleted" } }, "required": [ "id", "name", "workspace_id", "is_deleted" ], "title": "DatasetGroup" }, "CreateFolderRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The name of the folder. Must be unique within its parent folder." }, "parent_id": { "type": "integer", "nullable": true, "description": "The ID of the parent folder. If null or not provided, the folder will be created at the root level of the workspace." }, "workspace_id": { "type": "integer", "minimum": 1, "description": "Optional workspace ID. If not provided, uses the workspace associated with your API key." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." } }, "title": "CreateFolderRequest" }, "CreateFolderSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates if the operation was successful" }, "folder": { "$ref": "#/components/schemas/Folder" } }, "title": "CreateFolderSuccessResponse" }, "Folder": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the folder" }, "name": { "type": "string", "description": "The name of the folder" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the folder was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the folder was last updated" }, "path": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "JSON array representing the folder hierarchy path. Contains the IDs and names of all parent folders. Null for root-level folders." }, "workspace_id": { "type": "integer", "description": "ID of the workspace this folder belongs to" }, "parent_id": { "type": "integer", "nullable": true, "description": "ID of the parent folder. Null for root-level folders." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings for the folder." } }, "title": "Folder" }, "FolderExistsError": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "title": "FolderExistsError" }, "ParentFolderNotFoundError": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "title": "ParentFolderNotFoundError" }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "title": "UnauthorizedError" }, "FolderNotFoundError": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "title": "FolderNotFoundError" }, "UpdateFolderRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The new name for the folder. Must be unique within its parent folder." } }, "title": "UpdateFolderRequest" }, "EntityType": { "type": "string", "enum": [ "FOLDER", "PROMPT", "SNIPPET", "WORKFLOW", "DATASET", "REPORT", "AB_TEST", "INPUT_VARIABLE_SET" ], "description": "The type of entity. SNIPPET is a pseudo-entity type representing completion-type prompts." }, "FolderEntity": { "type": "object", "required": [ "id", "name", "type", "path" ], "properties": { "id": { "type": "integer", "description": "Unique identifier for the entity" }, "name": { "type": "string", "description": "Name of the entity" }, "type": { "$ref": "#/components/schemas/EntityType" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the entity was created" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the entity was last updated" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of the folder containing this entity. Null for root-level entities." }, "path": { "type": "array", "items": { "type": "string" }, "description": "Array of folder names representing the entity's location in the folder hierarchy." }, "metadata": { "nullable": true, "description": "Type-specific metadata. Included only when include_metadata=true.", "oneOf": [ { "$ref": "#/components/schemas/PromptEntityMetadata" }, { "$ref": "#/components/schemas/WorkflowEntityMetadata" }, { "$ref": "#/components/schemas/DatasetEntityMetadata" }, { "type": "object" } ] }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to this entity." } }, "title": "FolderEntity" }, "PromptEntityMetadata": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "enum": [ "chat", "completion" ], "description": "The prompt template type." }, "latest_version_number": { "type": "integer", "nullable": true, "description": "The latest version number of the prompt." } }, "title": "PromptEntityMetadata" }, "WorkflowEntityMetadata": { "type": "object", "properties": { "latest_version_number": { "type": "integer", "nullable": true, "description": "The latest version number of the workflow." } }, "title": "WorkflowEntityMetadata" }, "DatasetEntityMetadata": { "type": "object", "properties": { "isDraft": { "type": "boolean", "description": "Whether the dataset group only has draft versions (no published versions)." }, "latest_version_number": { "type": "integer", "nullable": true, "description": "The latest published version number of the dataset." } }, "title": "DatasetEntityMetadata" }, "ListFolderEntitiesResponse": { "type": "object", "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/FolderEntity" }, "description": "List of entities matching the query." } }, "title": "ListFolderEntitiesResponse" }, "EntityReference": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The ID of the entity." }, "type": { "$ref": "#/components/schemas/EntityType" } }, "title": "EntityReference" }, "MoveFolderEntitiesRequest": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" }, "description": "List of entities to move." }, "folder_id": { "type": "integer", "nullable": true, "description": "The ID of the destination folder. If null or not provided, entities are moved to the workspace root." }, "workspace_id": { "type": "integer", "description": "The ID of the workspace." } }, "title": "MoveFolderEntitiesRequest" }, "DeleteFolderEntitiesRequest": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "items": { "$ref": "#/components/schemas/EntityReference" }, "description": "List of entities to delete." }, "cascade": { "type": "boolean", "default": false, "description": "When true, recursively deletes all contents of any folders in the entities list. When false, attempting to delete a non-empty folder returns an error." }, "workspace_id": { "type": "integer", "description": "The ID of the workspace." } }, "title": "DeleteFolderEntitiesRequest" }, "FolderEntitiesCountResponse": { "type": "object", "properties": { "moved_count": { "type": "integer", "description": "The number of entities affected by the operation." } }, "title": "FolderEntitiesCountResponse" }, "ResolveFolderIdResponse": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the resolved folder." } }, "title": "ResolveFolderIdResponse" }, "OtlpExportTraceServiceRequest": { "type": "object", "title": "ExportTraceServiceRequest", "description": "An OTLP ExportTraceServiceRequest in JSON encoding. See the [OTLP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request) for the full schema.", "properties": { "resourceSpans": { "type": "array", "description": "An array of ResourceSpans. Each element describes spans from a single instrumented resource.", "items": { "type": "object", "properties": { "resource": { "type": "object", "description": "The resource that produced the spans.", "properties": { "attributes": { "type": "array", "description": "Resource attributes as key-value pairs.", "items": { "$ref": "#/components/schemas/OtlpKeyValue" } } } }, "scopeSpans": { "type": "array", "description": "An array of ScopeSpans, grouping spans by instrumentation scope.", "items": { "type": "object", "properties": { "scope": { "type": "object", "description": "The instrumentation scope that produced the spans.", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "spans": { "type": "array", "description": "Array of Span objects.", "items": { "$ref": "#/components/schemas/OtlpSpan" } } } } } } } } } }, "OtlpSpan": { "type": "object", "title": "Span", "description": "A single OTLP span. See the [OTLP Span spec](https://opentelemetry.io/docs/specs/otel/trace/api/#span) for full details.", "required": [ "traceId", "spanId", "name", "startTimeUnixNano" ], "properties": { "traceId": { "type": "string", "description": "Hex-encoded trace ID (32 hex characters / 16 bytes).", "minLength": 32, "maxLength": 32 }, "spanId": { "type": "string", "description": "Hex-encoded span ID (16 hex characters / 8 bytes).", "minLength": 16, "maxLength": 16 }, "parentSpanId": { "type": "string", "description": "Hex-encoded parent span ID. Empty or omitted for root spans." }, "name": { "type": "string", "description": "The name of the span." }, "kind": { "type": "integer", "description": "Span kind: 0=UNSPECIFIED, 1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER.", "enum": [ 0, 1, 2, 3, 4, 5 ] }, "startTimeUnixNano": { "type": "string", "description": "Start time in nanoseconds since Unix epoch, encoded as a string." }, "endTimeUnixNano": { "type": "string", "description": "End time in nanoseconds since Unix epoch, encoded as a string." }, "attributes": { "type": "array", "description": "Span attributes as key-value pairs. GenAI semantic convention attributes (e.g. `gen_ai.request.model`, `gen_ai.usage.input_tokens`) are automatically extracted.", "items": { "$ref": "#/components/schemas/OtlpKeyValue" } }, "status": { "type": "object", "description": "Span status.", "properties": { "code": { "type": "integer", "description": "Status code: 0=UNSET, 1=OK, 2=ERROR.", "enum": [ 0, 1, 2 ] }, "message": { "type": "string", "description": "Status message (typically set for ERROR status)." } } }, "events": { "type": "array", "description": "Span events (e.g. exceptions).", "items": { "type": "object", "properties": { "timeUnixNano": { "type": "string" }, "name": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/OtlpKeyValue" } } } } }, "links": { "type": "array", "description": "Links to other spans.", "items": { "type": "object", "properties": { "traceId": { "type": "string" }, "spanId": { "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/OtlpKeyValue" } } } } } } }, "OtlpKeyValue": { "type": "object", "title": "KeyValue", "description": "An OTLP attribute key-value pair.", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "object", "description": "The attribute value. Exactly one of the value fields must be set.", "properties": { "stringValue": { "type": "string" }, "intValue": { "type": "string" }, "doubleValue": { "type": "number" }, "boolValue": { "type": "boolean" }, "arrayValue": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "object" } } } } } } } }, "OtlpExportTraceServiceResponse": { "type": "object", "title": "ExportTraceServiceResponse", "description": "Response to an OTLP trace export request.", "properties": { "partialSuccess": { "type": [ "object", "null" ], "description": "Present only when some spans were rejected. Null when all spans were accepted.", "properties": { "rejectedSpans": { "type": "integer", "description": "The number of spans that were rejected." }, "errorMessage": { "type": "string", "description": "A human-readable error message describing why spans were rejected." } } } } }, "RequestLogQuery": { "type": "object", "title": "RequestLogQuery", "description": "Canonical request-log query payload — the filter / search / sort fields shared by `POST /api/public/v2/requests/search` (which also accepts pagination + `include_prompt_name`) and `POST /api/public/v2/requests/analytics`.", "properties": { "filter_group": { "nullable": true, "description": "Nested filter group with AND/OR logic. Use this for complex queries.", "$ref": "#/components/schemas/StructuredFilterGroup" }, "q": { "type": "string", "nullable": true, "description": "Free-text search query. Searches across the prompt input and LLM output text using fuzzy prefix matching." }, "sort_by": { "type": "string", "nullable": true, "enum": [ "request_start_time", "input_tokens", "output_tokens", "cost", "latency_ms", "status" ], "description": "Field to sort results by. Does not affect aggregated output for `/requests/analytics`." }, "sort_order": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "description": "Sort direction. Must be provided together with sort_by." }, "metadata_cost_breakdown_key": { "type": "string", "nullable": true, "description": "When provided, the analytics response includes a `metadataValueBreakdown` array with cost and request counts for each value of this metadata key. Omit or pass null to get an aggregate breakdown across the top metadata keys." } }, "example": { "filter_group": { "logic": "AND", "filters": [ { "field": "engine", "operator": "is", "value": "gpt-4o" } ] }, "sort_by": "request_start_time", "sort_order": "desc" } }, "RequestAnalyticsLatencyByDay": { "type": "object", "description": "Per-bucket latency percentiles in seconds. Keys are bucket dates (e.g. `2025-03-15`); values are seconds.", "properties": { "average_latency": { "type": "object", "additionalProperties": { "type": "number" } }, "p50_latency": { "type": "object", "additionalProperties": { "type": "number" } }, "p90_latency": { "type": "object", "additionalProperties": { "type": "number" } }, "p95_latency": { "type": "object", "additionalProperties": { "type": "number" } } } }, "RequestAnalyticsDimensionLatency": { "type": "object", "description": "Per-dimension (model / prompt template / provider) latency series. Each percentile is a list of `[date, seconds]` pairs.", "properties": { "average_latency": { "type": "array", "items": { "type": "array", "items": {} } }, "p50_latency": { "type": "array", "items": { "type": "array", "items": {} } }, "p90_latency": { "type": "array", "items": { "type": "array", "items": {} } }, "p95_latency": { "type": "array", "items": { "type": "array", "items": {} } } } }, "RequestAnalyticsStat": { "type": "object", "description": "One time-series bucket.", "properties": { "date": { "type": "string", "description": "ISO bucket key (e.g. `2025-03-15`)." }, "dateLabel": { "type": "string", "description": "Human-readable bucket label." }, "requests": { "type": "integer" }, "tokens": { "type": "integer" }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "cost": { "type": "number" }, "latency": { "type": "number", "description": "Average latency in seconds." }, "cachedTokens": { "type": "integer" }, "thinkingTokens": { "type": "integer" }, "traceShare": { "type": "number", "description": "Fraction of requests in the bucket that have a trace." }, "statusCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "outputShapeCounts": { "type": "object", "properties": { "json": { "type": "integer" }, "toolCall": { "type": "integer" }, "plainText": { "type": "integer" } } }, "avgTurnCount": { "type": "number" }, "avgToolCallCount": { "type": "number" }, "toolCallCountP95": { "type": "number", "nullable": true } } }, "RequestAnalyticsBreakdownEntry": { "type": "object", "description": "Aggregated breakdown row (provider / prompt / tag).", "properties": { "provider": { "type": "string", "description": "Set on provider breakdown rows." }, "promptId": { "type": "string", "description": "Set on prompt breakdown rows." }, "tag": { "type": "string", "description": "Set on tag breakdown rows." }, "requests": { "type": "integer" }, "cost": { "type": "number" }, "tokens": { "type": "integer" }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" } } }, "RequestAnalyticsToolLatency": { "type": "object", "description": "Per-tool latency stats.", "properties": { "toolName": { "type": "string" }, "requests": { "type": "integer" }, "avgLatencySeconds": { "type": "number", "nullable": true }, "minLatencySeconds": { "type": "number", "nullable": true }, "maxLatencySeconds": { "type": "number", "nullable": true } } }, "RequestAnalyticsResponse": { "type": "object", "title": "RequestAnalyticsResponse", "description": "Aggregated analytics across the matching request logs. Bucket size is selected automatically based on the filter time range (seconds → minutes → hours → days).", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "chartInterval": { "type": "object", "description": "Bucket-interval metadata describing how the time-series was bucketed.", "properties": { "interval": { "type": "string" }, "bucketSizeMs": { "type": "integer" }, "bucketMinutes": { "type": "integer", "nullable": true } } }, "averageLatency": { "type": "number", "description": "Overall average latency across all matching requests, in seconds." }, "totalCost": { "type": "number" }, "totalTokens": { "type": "integer" }, "totalRequests": { "type": "integer" }, "totalCachedTokens": { "type": "integer" }, "totalThinkingTokens": { "type": "integer" }, "cacheTokenRatio": { "type": "number", "nullable": true, "description": "`totalCachedTokens / total_input_tokens`, or null when there are no input tokens." }, "stats": { "type": "array", "description": "Per-bucket time-series.", "items": { "$ref": "#/components/schemas/RequestAnalyticsStat" } }, "mostUsedModels": { "type": "array", "description": "List of `[modelName, requestCount]` pairs ordered by usage.", "items": { "type": "array", "items": {} } }, "modelRequestsByDay": { "type": "object", "description": "Map of model name → list of `[date, requestCount]` pairs.", "additionalProperties": { "type": "array", "items": { "type": "array", "items": {} } } }, "mostUsedPromptTemplates": { "type": "array", "items": { "type": "object", "properties": { "promptId": { "type": "string" }, "requests": { "type": "integer" }, "promptName": { "type": "string", "nullable": true } } } }, "promptTemplateRequestsByDay": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": {} } } }, "providerRequestsByDay": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": {} } } }, "latency": { "$ref": "#/components/schemas/RequestAnalyticsLatencyByDay" }, "latencyByModelByDay": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RequestAnalyticsDimensionLatency" } }, "latencyByPromptTemplateByDay": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RequestAnalyticsDimensionLatency" } }, "latencyByProviderByDay": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RequestAnalyticsDimensionLatency" } }, "errorTypes": { "type": "array", "items": { "type": "object", "properties": { "errorType": { "type": "string" }, "requests": { "type": "integer" } } } }, "providerBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/RequestAnalyticsBreakdownEntry" } }, "promptBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/RequestAnalyticsBreakdownEntry" } }, "tagsBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/RequestAnalyticsBreakdownEntry" } }, "metadataKeysTop": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "requests": { "type": "integer" } } } }, "outputKeysTop": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "requests": { "type": "integer" } } } }, "toolsLatency": { "type": "array", "items": { "$ref": "#/components/schemas/RequestAnalyticsToolLatency" } }, "toolsUsageBars": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "requests": { "type": "integer" } } } }, "metadataValueBreakdown": { "type": "array", "description": "Cost and request count breakdown by metadata key-value pairs. When `metadata_cost_breakdown_key` is set in the request, all entries share that key and the `label` equals the value. Otherwise entries span the top key-value combinations and `label` is `key = value`. Ordered by cost descending; up to 50 entries.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The metadata key." }, "value": { "type": "string", "description": "The metadata value." }, "label": { "type": "string", "description": "Display label. Equals `value` when filtered to a single key; equals `key = value` in the aggregate view." }, "requests": { "type": "integer", "description": "Number of requests with this key-value pair." }, "cost": { "type": "number", "description": "Total cost for requests with this key-value pair, in USD." } } } } } }, "SearchRequestLogsRequest": { "title": "SearchRequestLogsRequest", "description": "Search and filter request logs with structured filters, free-text search, sorting, and pagination. Extends `RequestLogQuery` with pagination and `include_prompt_name`.", "allOf": [ { "$ref": "#/components/schemas/RequestLogQuery" }, { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "nullable": true, "description": "Page number for pagination. Defaults to 1." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 25, "nullable": true, "description": "Number of results per page. Defaults to 10, maximum 25." }, "include_prompt_name": { "type": "boolean", "nullable": true, "description": "When true, includes the prompt template name in each result item. Defaults to false." } } } ], "example": { "filter_group": { "logic": "AND", "filters": [ { "field": "cost", "operator": "gte", "value": 0.1 } ] }, "page": 1, "per_page": 25, "sort_by": "cost", "sort_order": "desc" } }, "StructuredFilter": { "type": "object", "title": "StructuredFilter", "description": "A single filter condition on a request log field.", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "The request log field to filter on. Intent fields are virtual fields that classify request content by tone and do not require any additional logging configuration. `user_intent` classifies the user's message; valid values: `frustrated`, `satisfied`, `curious`. `agent_intent` classifies the agent's response; valid values: `apologetic`, `refusal`, `uncertain`. Intent fields support operators: `is`, `is_not`, `in`, `not_in`.", "enum": [ "pl_id", "prompt_id", "engine", "provider_type", "input_text", "output_text", "prompt_version_number", "input_tokens", "output_tokens", "cost", "latency_ms", "request_start_time", "request_end_time", "status", "is_json", "is_tool_call", "is_plain_text", "tags", "metadata_keys", "metadata", "tool_names", "output", "output_keys", "input_variables", "input_variable_keys", "user_intent", "agent_intent" ] }, "operator": { "type": "string", "description": "The comparison operator.", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "eq", "neq", "gt", "gte", "lt", "lte", "between", "before", "after", "is_true", "is_false", "is_empty", "is_not_empty", "is_null", "is_not_null", "key_equals", "key_not_equals", "key_contains" ] }, "value": { "description": "The value to compare against. Type depends on the field and operator.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array" }, { "type": "null" } ] }, "nested_key": { "type": "string", "nullable": true, "description": "Required for nested fields (metadata, output, input_variables). Specifies which key within the nested object to filter on." } } }, "StructuredFilterGroup": { "type": "object", "title": "StructuredFilterGroup", "description": "A group of filters combined with AND or OR logic. Can be nested recursively.", "required": [ "filters" ], "properties": { "logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "AND", "description": "How to combine the filters in this group." }, "filters": { "type": "array", "description": "List of filters or nested filter groups.", "items": { "oneOf": [ { "$ref": "#/components/schemas/StructuredFilter" }, { "$ref": "#/components/schemas/StructuredFilterGroup" } ] } } } }, "SearchRequestLogsResponse": { "type": "object", "title": "SearchRequestLogsResponse", "description": "Paginated search results.", "properties": { "success": { "type": "boolean", "description": "Indicates the request was successful." }, "items": { "type": "array", "description": "List of matching request log summaries.", "items": { "$ref": "#/components/schemas/RequestLogSearchResult" } }, "page": { "type": "integer", "description": "Current page number." }, "pages": { "type": "integer", "description": "Total number of pages." }, "per_page": { "type": "integer", "description": "Number of results per page." }, "total": { "type": "integer", "description": "Total number of matching results." }, "has_next": { "type": "boolean", "description": "Whether there are more pages after the current one." }, "has_prev": { "type": "boolean", "description": "Whether there are pages before the current one." }, "next_num": { "type": "integer", "nullable": true, "description": "Next page number, or null if on the last page." }, "prev_num": { "type": "integer", "nullable": true, "description": "Previous page number, or null if on the first page." } } }, "ExternalId": { "properties": { "source": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Source", "description": "The external system or namespace that owns the ID." }, "external_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "External Id", "description": "The identifier for this entity in the external system." } }, "type": "object", "required": [ "source", "external_id" ], "additionalProperties": false, "title": "ExternalId", "description": "Customer-defined mapping between a PromptLayer entity and an external system identifier." }, "AttachExternalIdRequest": { "properties": { "source": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Source", "description": "The external system or namespace that owns the ID." }, "external_id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "External Id", "description": "The identifier for this entity in the external system." } }, "type": "object", "required": [ "source", "external_id" ], "additionalProperties": false, "title": "AttachExternalIdRequest", "description": "External ID mapping to attach to an entity." }, "ExternalIdAttachResponse": { "properties": { "success": { "type": "boolean", "const": true, "default": true, "title": "Success" }, "external_id": { "$ref": "#/components/schemas/ExternalId" } }, "type": "object", "required": [ "success", "external_id" ], "title": "ExternalIdAttachResponse" }, "ExternalIdsListResponse": { "properties": { "success": { "type": "boolean", "const": true, "default": true, "title": "Success" }, "external_ids": { "items": { "$ref": "#/components/schemas/ExternalId" }, "type": "array", "title": "External Ids" } }, "type": "object", "required": [ "success", "external_ids" ], "title": "ExternalIdsListResponse" }, "ExternalIdDeleteResponse": { "properties": { "success": { "type": "boolean", "const": true, "default": true, "title": "Success" } }, "type": "object", "required": [ "success" ], "title": "ExternalIdDeleteResponse" }, "ExternalIdErrorResponse": { "properties": { "success": { "type": "boolean", "const": false, "default": false, "title": "Success" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "ExternalIdErrorResponse" }, "ListPromptTemplateItem": { "properties": { "id": { "type": "integer", "title": "Id" }, "prompt_name": { "type": "string", "title": "Prompt Name" }, "prompt_template": { "oneOf": [ { "$ref": "#/components/schemas/CompletionPrompt" }, { "$ref": "#/components/schemas/ChatPrompt" } ], "title": "Prompt Template", "discriminator": { "propertyName": "type", "mapping": { "chat": "#/components/schemas/ChatPrompt", "completion": "#/components/schemas/CompletionPrompt" } } }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/Metadata" }, { "type": "null" } ] }, "commit_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commit Message" }, "llm_kwargs": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Llm Kwargs", "description": "When you optionally specify `provider` in the body, `llm_kwargs` will be returned for that specific provider and you can pass these kwargs to the provider's API directly. **Important:** This object's structure is provider-specific and may change without notice as LLM providers update their APIs. For stable, provider-agnostic prompt data, use `prompt_template` instead." }, "version": { "type": "integer", "title": "Version" }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to the prompt template.", "title": "External Ids" }, "is_snippet": { "type": "boolean", "title": "Is Snippet", "description": "Whether this prompt template record is a snippet." } }, "type": "object", "required": [ "id", "prompt_name", "prompt_template", "external_ids" ], "title": "ListPromptTemplateItem" }, "RateLimitError": { "type": "object", "description": "Error returned when an endpoint rate limit is exceeded.", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "error": { "type": "string", "nullable": true } } }, "EvaluationColumnDefinition": { "type": "object", "title": "EvaluationColumnDefinition", "description": "Definition for a column in an evaluation pipeline. The configuration schema depends on column_type.", "required": [ "column_type", "name", "configuration" ], "properties": { "column_type": { "type": "string", "enum": [ "PROMPT_TEMPLATE", "CODE_EXECUTION", "ENDPOINT", "WORKFLOW", "MCP", "HUMAN", "CONVERSATION_SIMULATOR", "LLM_ASSERTION", "AI_DATA_EXTRACTION", "COMPARE", "CONTAINS", "REGEX", "COSINE_SIMILARITY", "ABSOLUTE_NUMERIC_DISTANCE", "JSON_PATH", "XML_PATH", "REGEX_EXTRACTION", "PARSE_VALUE", "VARIABLE", "ASSERT_VALID", "COALESCE", "COMBINE_COLUMNS", "COUNT", "MATH_OPERATOR", "MIN_MAX" ], "description": "Type of evaluation column to create." }, "name": { "type": "string", "description": "Display name for the column. Must be unique within the pipeline." }, "configuration": { "type": "object", "additionalProperties": true, "description": "Column-type-specific configuration. See Node & Column Types for details." }, "position": { "type": "integer", "minimum": 1, "nullable": true, "description": "1-based position in the pipeline. Auto-assigned if omitted." }, "is_part_of_score": { "type": "boolean", "default": false, "description": "When true, PromptLayer includes this column in built-in scoring by averaging its values." } }, "example": { "column_type": "LLM_ASSERTION", "name": "Accuracy Check", "configuration": { "source": "response", "prompt": "Is this response accurate?" }, "is_part_of_score": true } }, "ScoreConfiguration": { "type": "object", "title": "ScoreConfiguration", "description": "Custom scoring configuration. The code receives a data variable containing row dictionaries and must return an object with at least a score key from 0 to 100.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Python or JavaScript code used to calculate the score." }, "code_language": { "type": "string", "enum": [ "PYTHON", "JAVASCRIPT" ], "default": "PYTHON", "description": "Language used by the scoring code." } }, "example": { "code": "score = sum(1 for row in data if row.get(\"Accuracy Check\") is True) / len(data) * 100 if data else 0\nreturn {\"score\": score}", "code_language": "PYTHON" } }, "EvaluationPipelineSummary": { "type": "object", "title": "EvaluationPipelineSummary", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "score_configuration": { "anyOf": [ { "$ref": "#/components/schemas/ScoreConfiguration" }, { "type": "null" } ] } } }, "ReportColumnSummary": { "type": "object", "title": "ReportColumnSummary", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "column_type": { "type": "string", "enum": [ "PROMPT_TEMPLATE", "CODE_EXECUTION", "ENDPOINT", "WORKFLOW", "MCP", "HUMAN", "CONVERSATION_SIMULATOR", "LLM_ASSERTION", "AI_DATA_EXTRACTION", "COMPARE", "CONTAINS", "REGEX", "COSINE_SIMILARITY", "ABSOLUTE_NUMERIC_DISTANCE", "JSON_PATH", "XML_PATH", "REGEX_EXTRACTION", "PARSE_VALUE", "VARIABLE", "ASSERT_VALID", "COALESCE", "COMBINE_COLUMNS", "COUNT", "MATH_OPERATOR", "MIN_MAX", "DATASET" ] }, "position": { "type": "integer" }, "configuration": { "type": "object", "additionalProperties": true } } }, "CreateEvaluationPipelineRequest": { "type": "object", "title": "CreateEvaluationPipelineRequest", "required": [ "dataset_group_id" ], "properties": { "dataset_group_id": { "type": "integer", "description": "ID of the dataset group to use." }, "name": { "type": "string", "nullable": true, "description": "Name for the pipeline. Auto-generated if omitted." }, "folder_id": { "type": "integer", "nullable": true, "description": "Folder ID for organization." }, "dataset_version_number": { "type": "integer", "nullable": true, "description": "Specific dataset version. Uses latest published version if omitted." }, "columns": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/EvaluationColumnDefinition" }, "description": "Evaluation columns to add to the pipeline." }, "score_configuration": { "anyOf": [ { "$ref": "#/components/schemas/ScoreConfiguration" }, { "type": "null" } ], "description": "Optional custom scoring logic." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings to attach to the pipeline." } } }, "CreateEvaluationPipelineResponse": { "type": "object", "title": "CreateEvaluationPipelineResponse", "required": [ "success", "report_id", "external_ids" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "report_id": { "type": "integer", "description": "ID of the created evaluation pipeline." }, "report_columns": { "type": "array", "items": { "$ref": "#/components/schemas/ReportColumnSummary" }, "description": "Columns created on the pipeline." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings attached to the pipeline." } } }, "UpdateReportScoreCardRequest": { "type": "object", "title": "UpdateReportScoreCardRequest", "required": [ "column_names" ], "properties": { "column_names": { "type": "array", "items": { "type": "string" }, "description": "Column names to include in the score calculation." }, "code": { "type": "string", "nullable": true, "description": "Optional custom Python or JavaScript scoring code. The code receives data and must return an object with a score key." }, "code_language": { "type": "string", "enum": [ "PYTHON", "JAVASCRIPT" ], "default": "PYTHON", "description": "Language used by the custom scoring code." } } }, "UpdateReportScoreCardResponse": { "type": "object", "title": "UpdateReportScoreCardResponse", "required": [ "success", "report" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "report": { "$ref": "#/components/schemas/EvaluationPipelineSummary" } } }, "EditReportColumnRequest": { "type": "object", "title": "EditReportColumnRequest", "required": [ "report_id", "column_type" ], "properties": { "report_id": { "type": "integer", "description": "Parent evaluation pipeline ID. Must match the column parent." }, "column_type": { "type": "string", "enum": [ "PROMPT_TEMPLATE", "CODE_EXECUTION", "ENDPOINT", "WORKFLOW", "MCP", "HUMAN", "CONVERSATION_SIMULATOR", "LLM_ASSERTION", "AI_DATA_EXTRACTION", "COMPARE", "CONTAINS", "REGEX", "COSINE_SIMILARITY", "ABSOLUTE_NUMERIC_DISTANCE", "JSON_PATH", "XML_PATH", "REGEX_EXTRACTION", "PARSE_VALUE", "VARIABLE", "ASSERT_VALID", "COALESCE", "COMBINE_COLUMNS", "COUNT", "MATH_OPERATOR", "MIN_MAX" ], "description": "Replacement column type. DATASET columns cannot be edited." }, "configuration": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Replacement column configuration. Schema depends on column_type." }, "name": { "type": "string", "nullable": true, "description": "New column name. Must be unique within the pipeline." }, "position": { "type": "integer", "minimum": 1, "nullable": true, "description": "New 1-based position. Cannot overwrite dataset columns." } } }, "EditReportColumnResponse": { "type": "object", "title": "EditReportColumnResponse", "required": [ "success", "report_column" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "report_column": { "$ref": "#/components/schemas/ReportColumnSummary" } } }, "RenameReportRequest": { "type": "object", "title": "RenameReportRequest", "description": "Provide name, tags, or both. At least one field is required.", "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "New pipeline name." }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Replacement tags. Pass an empty array to clear all tags." } } }, "RenameReportResponse": { "type": "object", "title": "RenameReportResponse", "required": [ "success", "report" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "report": { "$ref": "#/components/schemas/EvaluationPipelineSummary" } } }, "DeleteReportResponse": { "type": "object", "title": "DeleteReportResponse", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } } }, "CreateDatasetGroupRequest": { "type": "object", "title": "CreateDatasetGroupRequest", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the dataset group. Must be unique within the workspace." }, "workspace_id": { "type": "integer", "nullable": true, "description": "Workspace ID. Defaults to the workspace associated with the API key." }, "folder_id": { "type": "integer", "nullable": true, "description": "Folder ID to create the dataset group in. Omit to create at the workspace root." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "External ID mappings to attach to the dataset group." } } }, "CreateDatasetGroupResponse": { "type": "object", "title": "CreateDatasetGroupResponse", "required": [ "success", "dataset_group", "dataset", "external_ids" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "dataset_group": { "anyOf": [ { "$ref": "#/components/schemas/DatasetGroup" }, { "type": "object", "additionalProperties": true } ] }, "dataset": { "anyOf": [ { "$ref": "#/components/schemas/Dataset" }, { "type": "object", "additionalProperties": true } ], "description": "Initial draft dataset created with version_number = -1." }, "external_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" } } } }, "CreateDatasetVersionFromFilterParamsRequest": { "type": "object", "title": "CreateDatasetVersionFromFilterParamsRequest", "required": [ "dataset_group_id" ], "properties": { "dataset_group_id": { "type": "integer", "description": "Dataset group that will receive the generated dataset version." }, "request_log_ids": { "type": "array", "items": { "type": "integer" }, "maxItems": 50000, "nullable": true, "description": "Explicit request log IDs to snapshot. When provided, this mode takes precedence over filter_group." }, "filter_group": { "anyOf": [ { "$ref": "#/components/schemas/StructuredFilterGroup" }, { "type": "null" } ], "description": "Structured request-log filters used to populate the dataset asynchronously." }, "q": { "type": "string", "nullable": true, "description": "Free-text request-log search query applied with filter_group." }, "sort_by": { "type": "string", "enum": [ "request_start_time", "input_tokens", "output_tokens", "cost", "latency_ms", "status" ], "nullable": true }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "nullable": true }, "variables_to_parse": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Request fields or variables to parse into dataset columns." }, "limit": { "type": "integer", "nullable": true, "minimum": 1, "description": "Maximum number of request logs to include. When set, only the first N matching rows (in the current sort order) are added to the dataset version." } } }, "CreateDatasetVersionFromFilterParamsResponse": { "type": "object", "title": "CreateDatasetVersionFromFilterParamsResponse", "required": [ "success", "dataset_id", "dataset_group_id", "version_number" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "dataset_id": { "type": "integer" }, "dataset_group_id": { "type": "integer" }, "version_number": { "type": "integer", "description": "Version number of the draft or generated dataset version." } } }, "DatasetRowCell": { "type": "object", "title": "DatasetRowCell", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "dataset" ] }, "value": { "description": "Dataset cell value." } } }, "EvaluationRowCell": { "type": "object", "title": "EvaluationRowCell", "required": [ "type", "status" ], "properties": { "type": { "type": "string", "enum": [ "eval" ] }, "status": { "type": "string", "description": "Evaluation cell status, such as PASSED, FAILED, RUNNING, or SKIPPED." }, "value": { "nullable": true, "description": "Evaluation result value." }, "error_message": { "type": "string", "nullable": true, "description": "Error details for failed cells." } } }, "DatasetRowsResponse": { "type": "object", "title": "DatasetRowsResponse", "required": [ "success", "columns", "rows", "page", "per_page", "pages", "total" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "pages": { "type": "integer" }, "total": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRowCell" } }, "description": "Rows of dataset cells in the same order as columns." } } }, "EvaluationRowsResponse": { "type": "object", "title": "EvaluationRowsResponse", "required": [ "success", "columns", "rows", "page", "per_page", "pages", "total" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "pages": { "type": "integer" }, "total": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DatasetRowCell" }, { "$ref": "#/components/schemas/EvaluationRowCell" } ] } }, "description": "Rows containing dataset cells followed by evaluation result cells." } } }, "RequestLogDetailResponse": { "type": "object", "title": "RequestLogDetailResponse", "required": [ "success", "prompt_blueprint", "request_id" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "prompt_blueprint": { "type": "object", "additionalProperties": true, "description": "Provider-agnostic prompt blueprint that can be replayed." }, "request_id": { "type": "integer" }, "provider": { "type": "string" }, "model": { "type": "string" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "tokens": { "type": "integer" }, "price": { "type": "number" }, "request_start_time": { "type": "string", "format": "date-time" }, "request_end_time": { "type": "string", "format": "date-time" }, "latency_ms": { "type": "number" }, "trace_id": { "type": "string", "nullable": true, "description": "Associated trace ID, if available." } } }, "TraceDetailResponse": { "type": "object", "title": "TraceDetailResponse", "required": [ "success", "trace_id", "spans" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "trace_id": { "type": "string" }, "spans": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Spans in this trace. Spans that created request logs include request_log_id." } } }, "SearchRequestSuggestionsResponse": { "type": "object", "title": "SearchRequestSuggestionsResponse", "required": [ "success", "values" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "values": { "type": "array", "items": { "type": "string" }, "description": "Suggested values for the requested field." } } }, "TrackPromptRequest": { "type": "object", "title": "TrackPromptRequest", "required": [ "prompt_name", "request_id" ], "properties": { "prompt_name": { "type": "string", "description": "Prompt template name to associate with the request." }, "prompt_input_variables": { "type": "object", "additionalProperties": true, "description": "Variables used to render the prompt." }, "request_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "PromptLayer request ID to update." }, "version": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "description": "Prompt template version to associate." }, "label": { "type": "string", "nullable": true, "description": "Release label to resolve to a prompt template version." } } }, "TrackMetadataRequest": { "type": "object", "title": "TrackMetadataRequest", "required": [ "request_id", "metadata" ], "properties": { "request_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "PromptLayer request ID to update." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Metadata dictionary to associate with the request." } } }, "TrackResponse": { "type": "object", "title": "TrackResponse", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "RequestLogSearchResult": { "type": "object", "title": "RequestLogSearchResult", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "engine": { "type": "string" }, "provider_type": { "type": "string" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "price": { "type": "number" }, "request_start_time": { "type": "string", "format": "date-time" }, "request_end_time": { "type": "string", "format": "date-time" }, "latency": { "type": "number" }, "tags_array": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "scores": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "prompt_name": { "type": "string", "nullable": true } } }, "CreateDatasetVersionFromFileRequest": { "type": "object", "title": "CreateDatasetVersionFromFileRequest", "required": [ "dataset_group_id", "file_name", "file_content_base64" ], "properties": { "dataset_group_id": { "type": "integer", "minimum": 1, "description": "ID of the dataset group where the new version will be created." }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the CSV or JSON file. Must end with .csv or .json." }, "file_content_base64": { "type": "string", "minLength": 1, "description": "Base64-encoded file content. Maximum decoded file size is 100MB." } } }, "CreateDatasetVersionFromFileResponse": { "type": "object", "title": "CreateDatasetVersionFromFileResponse", "required": [ "success", "message", "dataset_id" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "dataset_id": { "type": "integer", "description": "ID of the draft dataset created for asynchronous processing." } } }, "CreateDraftDatasetVersionRequest": { "type": "object", "title": "CreateDraftDatasetVersionRequest", "required": [ "dataset_group_id" ], "properties": { "dataset_group_id": { "type": "integer", "minimum": 1, "description": "ID of the dataset group to create a draft version for." }, "source_dataset_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Optional existing dataset version to copy rows from. Must belong to the same dataset group." } } }, "DraftDatasetVersionResponse": { "type": "object", "title": "DraftDatasetVersionResponse", "required": [ "success", "message", "draft_dataset_id" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "draft_dataset_id": { "type": "integer", "description": "ID of the draft dataset." } } }, "AddRequestLogToDatasetRequest": { "type": "object", "title": "AddRequestLogToDatasetRequest", "required": [ "dataset_group_id", "request_log_id" ], "properties": { "dataset_group_id": { "type": "integer", "minimum": 1, "description": "ID of the dataset group containing the draft." }, "request_log_id": { "type": "integer", "minimum": 1, "description": "ID of the request log to add as a dataset row." } } }, "SaveDraftDatasetVersionRequest": { "type": "object", "title": "SaveDraftDatasetVersionRequest", "required": [ "dataset_group_id" ], "properties": { "dataset_group_id": { "type": "integer", "minimum": 1, "description": "ID of the dataset group containing the draft to save." } } }, "AddTraceToDatasetRequest": { "type": "object", "title": "AddTraceToDatasetRequest", "required": [ "dataset_group_id", "trace_id" ], "properties": { "dataset_group_id": { "type": "integer", "minimum": 1, "description": "ID of the dataset group to add the trace row to." }, "trace_id": { "type": "string", "minLength": 1, "description": "ID of the trace to add as a dataset row." }, "span_id": { "type": "string", "minLength": 1, "nullable": true, "description": "Optional span ID. When omitted the row anchors on the trace's earliest root span (Trace export). When provided the row anchors on that span and its direct children become the columns (Span export)." } } }, "AddTraceToDatasetResponse": { "type": "object", "title": "AddTraceToDatasetResponse", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "draft_dataset_id": { "type": "integer", "description": "ID of the draft dataset the trace row was added to." }, "mode": { "type": "string", "enum": [ "trace", "span" ], "description": "Indicates whether the row was created from a full trace root (`trace`) or a specific span subtree (`span`)." } } }, "Table": { "type": "object", "description": "A Table — 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", "description": "Workspace that owns this resource; determined by the authenticated request scope." }, "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" } } }, "TableDetail": { "allOf": [ { "$ref": "#/components/schemas/Table" } ], "type": "object", "properties": { "sheet_row_counts": { "type": "object", "description": "Map of sheet_id → row count.", "additionalProperties": { "type": "integer" } } } }, "Sheet": { "type": "object", "description": "A sheet within a Table.", "properties": { "id": { "type": "string", "format": "uuid" }, "table_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "integer", "description": "Workspace that owns this resource; determined by the authenticated request scope." }, "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", "description": "Current sheet version number. It increments when sheet data, layout, score configuration, imports, or execution output changes." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Column": { "type": "object", "description": "A column within a Table sheet.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the column." }, "sheet_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "integer", "description": "Workspace that owns this resource; determined by the authenticated request scope." }, "title": { "type": "string", "description": "Display title of the column." }, "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", "description": "Whether this column is designated as an output column." } } }, "Cell": { "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 }, "input_hash": { "type": "string", "nullable": true, "description": "Hash of the inputs used to compute this cell, used for cache invalidation." }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the last update." }, "request_metrics": { "allOf": [ { "$ref": "#/components/schemas/SmartTableRequestMetrics" } ], "nullable": true, "description": "Execution metrics populated for prompt-template column cells. Present only when the cell has an associated request log." }, "execution_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Execution ID associated with the current or most recent computed value, when available." }, "last_computed_version": { "type": "integer", "nullable": true, "description": "Sheet version_count when this cell was last computed. Null for text cells, virtual cells, or cells that have not completed computation." }, "error_message": { "type": "string", "nullable": true, "description": "User-visible error message for failed computed cells, when available." } } }, "TableImportOperation": { "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 } } }, "SmartTableRequestMetrics": { "type": "object", "description": "Execution metrics for a prompt-template cell, derived from the underlying request log.", "properties": { "request_count": { "type": "integer", "description": "Number of LLM requests made to produce this cell's value." }, "request_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of the request logs associated with this cell." }, "latency_ms": { "type": "integer", "nullable": true, "description": "Total end-to-end latency in milliseconds." }, "price": { "type": "number", "nullable": true, "description": "Total cost in USD for all requests that produced this cell." }, "input_tokens": { "type": "integer", "nullable": true, "description": "Total number of input tokens across all requests." }, "output_tokens": { "type": "integer", "nullable": true, "description": "Total number of output tokens across all requests." }, "trace_ids": { "type": "array", "items": { "type": "string" }, "description": "Trace IDs linked to this cell (present when the cell was produced via an OpenTelemetry-traced workflow)." } } }, "ExecutionMetadataMetricAggregate": { "type": "object", "description": "Aggregated statistics for a single execution metric (e.g. price or latency) across all rows in a sheet.", "properties": { "metric_key": { "type": "string", "description": "Internal metric identifier. One of `price` or `latency_ms`.", "enum": [ "price", "latency_ms" ] }, "metric_label": { "type": "string", "nullable": true, "description": "Human-readable label for the metric." }, "count": { "type": "integer", "description": "Number of rows that have a value for this metric." }, "sum": { "type": "number", "description": "Sum of all metric values." }, "avg": { "type": "number", "nullable": true, "description": "Average metric value, or null if count is 0." }, "min": { "type": "number", "nullable": true, "description": "Minimum metric value, or null if count is 0." }, "max": { "type": "number", "nullable": true, "description": "Maximum metric value, or null if count is 0." }, "column_id": { "type": "string", "format": "uuid", "description": "ID of the system-managed metadata column for this metric. Omitted for sheet-level aggregates." }, "source_column_id": { "type": "string", "format": "uuid", "description": "ID of the prompt-template source column. Omitted for sheet-level aggregates." } }, "required": [ "metric_key", "count", "sum" ] }, "ExecutionMetadataAggregates": { "type": "object", "description": "Sheet-level and per-column aggregates for execution metrics (price and latency) across all prompt-template columns.", "properties": { "by_column_id": { "type": "object", "description": "Per-column aggregates keyed by the system-managed metadata column ID.", "additionalProperties": { "$ref": "#/components/schemas/ExecutionMetadataMetricAggregate" } }, "sheet": { "type": "object", "description": "Sheet-wide aggregates rolled up across all prompt-template columns.", "properties": { "by_metric": { "type": "object", "description": "Aggregates keyed by metric key (`price`, `latency_ms`).", "additionalProperties": { "$ref": "#/components/schemas/ExecutionMetadataMetricAggregate" } } }, "required": [ "by_metric" ] } }, "required": [ "by_column_id", "sheet" ] }, "ListTableSheetOperationsResponse": { "type": "object", "title": "ListTableSheetOperationsResponse", "required": [ "success", "sheet_id", "version", "total_cells", "status_counts", "pending_count", "active_operations" ], "properties": { "success": { "type": "boolean" }, "sheet_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "total_cells": { "type": "integer" }, "status_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "pending_count": { "type": "integer" }, "active_operations": { "type": "array", "items": { "$ref": "#/components/schemas/TableSheetOperation" } } }, "additionalProperties": false }, "CreateTableSheetOperationRequest": { "type": "object", "title": "CreateTableSheetOperationRequest", "properties": { "operation": { "type": "string", "enum": [ "recalculate" ], "default": "recalculate" }, "column_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "description": "Columns to recalculate. Text columns cannot be recalculated." }, "row_ids": { "type": "array", "nullable": true, "items": { "type": "integer", "minimum": 0 }, "description": "Zero-based row indices to recalculate. If omitted, matching cells across all rows are considered." }, "statuses": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "STALE", "QUEUED", "DISPATCHED", "RUNNING", "COMPLETED", "FAILED" ] }, "description": "Cell statuses to include. Defaults to stale cells. Pass an empty array to include all statuses." }, "confirmation_token": { "type": "string", "nullable": true, "description": "Confirmation token returned when the operation exceeds the confirmation threshold." } }, "additionalProperties": false }, "CreateTableSheetOperationResponse": { "title": "CreateTableSheetOperationResponse", "oneOf": [ { "$ref": "#/components/schemas/CreateTableSheetOperationQueuedResponse" }, { "$ref": "#/components/schemas/CreateTableSheetOperationNoopResponse" }, { "$ref": "#/components/schemas/CreateTableSheetOperationConfirmationResponse" } ] }, "GetTableSheetOperationResponse": { "type": "object", "title": "GetTableSheetOperationResponse", "required": [ "success", "operation" ], "properties": { "success": { "type": "boolean" }, "operation": { "$ref": "#/components/schemas/TableSheetOperation" } }, "additionalProperties": false }, "CancelTableSheetOperationResponse": { "type": "object", "title": "CancelTableSheetOperationResponse", "required": [ "success", "message", "operation_id", "execution_ids", "cancelled_cell_count" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "operation_id": { "type": "string" }, "execution_ids": { "type": "array", "items": { "type": "string" } }, "cancelled_cell_count": { "type": "integer" }, "not_started_reset_count": { "type": "integer" }, "running_invalidated_count": { "type": "integer" } } }, "TableSheetScoreResponse": { "type": "object", "title": "TableSheetScoreResponse", "required": [ "success", "sheet_id", "scoring_type", "columns", "aggregate_score", "total_rows", "scored_rows", "excluded_rows", "calculated_at", "score_matrix", "score_matrix_metrics", "status", "score_calculation_error", "has_custom_scoring", "score_configuration", "score_type", "overall_score", "details", "aggregate", "per_column" ], "properties": { "success": { "type": "boolean" }, "sheet_id": { "type": "string", "format": "uuid" }, "scoring_type": { "type": "string", "enum": [ "auto", "boolean", "numeric", "custom", null ], "nullable": true }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/TableSheetScoreColumn" } }, "aggregate_score": { "type": "number", "nullable": true }, "total_rows": { "type": "integer" }, "scored_rows": { "type": "integer" }, "excluded_rows": { "type": "integer" }, "calculated_at": { "type": "string", "format": "date-time", "nullable": true }, "score_matrix": { "type": "array", "nullable": true, "items": { "type": "array", "items": { "nullable": true, "oneOf": [ { "type": "number" }, { "type": "string" }, { "$ref": "#/components/schemas/TableSheetScoreCellObject" } ] } } }, "score_matrix_metrics": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TableSheetScoreMetric" } }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", null ], "nullable": true }, "score_calculation_error": { "type": "string", "nullable": true }, "has_custom_scoring": { "type": "boolean" }, "score_configuration": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TableSheetScoreConfiguration" } ] }, "score_type": { "type": "string", "enum": [ "none", "single_column", "multi_column", "custom" ] }, "overall_score": { "type": "number", "nullable": true }, "details": { "type": "object", "additionalProperties": true }, "aggregate": { "type": "object", "additionalProperties": true }, "per_column": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "ConfigureTableSheetScoreRequest": { "type": "object", "title": "ConfigureTableSheetScoreRequest", "properties": { "score_type": { "type": "string", "enum": [ "auto", "boolean", "numeric", "custom" ], "nullable": true, "description": "Scoring mode. Required when score_config is provided." }, "score_config": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Explicit score configuration." }, "column_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "description": "Column IDs to score." }, "column_names": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Column titles to score. Titles must be unique in the sheet." }, "code": { "type": "string", "minLength": 1, "maxLength": 50000, "nullable": true, "description": "Custom scoring code." }, "code_language": { "type": "string", "enum": [ "PYTHON", "JAVASCRIPT" ], "default": "PYTHON" }, "true_values": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Values treated as true for boolean scoring." }, "false_values": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Values treated as false for boolean scoring." }, "assertion_aggregation": { "type": "string", "enum": [ "all", "any", "mean" ], "nullable": true, "description": "Aggregation mode for assertion-style boolean scoring." } }, "additionalProperties": false }, "ConfigureTableSheetScoreResponse": { "type": "object", "title": "ConfigureTableSheetScoreResponse", "required": [ "success", "message", "score_configuration_id", "status", "requires_recalculation", "version" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "score_configuration_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "nullable": true, "description": "Returned as null by this endpoint. Use the recalculation endpoint to queue score calculation." }, "requires_recalculation": { "type": "boolean", "description": "Always true after updating the score configuration." }, "version": { "type": "integer" } } }, "RecalculateTableSheetScoreResponse": { "type": "object", "title": "RecalculateTableSheetScoreResponse", "required": [ "success", "score_configuration_id", "status" ], "properties": { "success": { "type": "boolean" }, "score_configuration_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "nullable": true, "enum": [ "queued", "running", "completed", "failed", null ] } } }, "ListTableSheetVersionsResponse": { "type": "object", "title": "ListTableSheetVersionsResponse", "required": [ "success", "data", "pagination", "filters", "count" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TableSheetVersion" }, "description": "Items returned on this page." }, "pagination": { "$ref": "#/components/schemas/PublicListPagination" }, "filters": { "$ref": "#/components/schemas/EmptyPublicFilters", "description": "Filters applied to this page. The cursor includes a hash of this filter set, so changing filters while reusing a cursor returns an invalid cursor error." }, "count": { "type": "integer", "description": "Number of items returned on this page." } }, "additionalProperties": false }, "CreateTableSheetVersionRequest": { "type": "object", "title": "CreateTableSheetVersionRequest", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "nullable": true, "description": "Version name. Required when source_version_id is omitted." }, "source_version_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Existing version to restore from while creating a new version." } }, "additionalProperties": false }, "GetTableSheetVersionResponse": { "type": "object", "title": "GetTableSheetVersionResponse", "required": [ "success", "version" ], "properties": { "success": { "type": "boolean" }, "version": { "$ref": "#/components/schemas/TableSheetVersion" } } }, "TableSheetScoreHistoryResponse": { "type": "object", "title": "TableSheetScoreHistoryResponse", "required": [ "success", "score_history" ], "properties": { "success": { "type": "boolean" }, "score_history": { "type": "object", "required": [ "points", "total_points", "returned_points", "resolution", "range", "max_points", "is_sampled" ], "properties": { "points": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_points": { "type": "integer" }, "returned_points": { "type": "integer" }, "resolution": { "type": "string", "enum": [ "auto", "raw", "min_max_bucket" ] }, "range": { "type": "string" }, "max_points": { "type": "integer" }, "is_sampled": { "type": "boolean" } } } } }, "CreateTableSheetFileImportRequest": { "type": "object", "title": "CreateTableSheetFileImportRequest", "required": [ "file_name", "file_content_base64" ], "properties": { "operation_id": { "type": "string", "nullable": true, "description": "Optional client-provided operation ID. A UUID is generated when omitted." }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "CSV file name. Must end with .csv." }, "file_content_base64": { "type": "string", "minLength": 1, "description": "Base64-encoded CSV file content." } }, "additionalProperties": false }, "TableSheetImportStartResponse": { "type": "object", "title": "TableSheetImportStartResponse", "required": [ "success", "message", "operation_id", "operation", "status_url" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "operation_id": { "type": "string" }, "operation": { "$ref": "#/components/schemas/TableImportOperation" }, "status_url": { "type": "string" } }, "additionalProperties": false }, "CreateTableSheetRequestLogImportRequest": { "type": "object", "title": "CreateTableSheetRequestLogImportRequest", "description": "Import request history into an existing Table sheet. Provide either request_log_ids or filter_group.", "properties": { "filter_group": { "nullable": true, "description": "Nested filter group with AND/OR logic. Use this for complex queries.", "$ref": "#/components/schemas/StructuredFilterGroup" }, "q": { "type": "string", "nullable": true, "description": "Free-text request-log search query applied with filter_group." }, "sort_by": { "type": "string", "nullable": true, "enum": [ "request_start_time", "input_tokens", "output_tokens", "cost", "latency_ms", "status" ], "description": "Field to sort matching request logs before import." }, "sort_order": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "description": "Sort direction. Must be provided together with sort_by." }, "metadata_cost_breakdown_key": { "type": "string", "nullable": true, "description": "Request-log query metadata key used by shared request-log query payloads." }, "operation_id": { "type": "string", "nullable": true, "description": "Optional client-provided operation ID. A UUID is generated when omitted." }, "request_log_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "nullable": true, "description": "Specific request log IDs to import.", "minItems": 1, "maxItems": 50000 }, "variables_to_parse": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Input variable names to parse from matching request logs." }, "include_fields": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Additional request log fields to include as columns." }, "limit": { "type": "integer", "minimum": 1, "nullable": true, "description": "Maximum number of matching request logs to import.", "maximum": 50000 } }, "additionalProperties": false }, "TableSheetOperation": { "type": "object", "title": "TableSheetOperation", "required": [ "operation_id", "operation", "status", "status_counts", "cell_count", "completed_count", "failed_count", "pending_count", "status_url" ], "properties": { "operation_id": { "type": "string" }, "operation": { "type": "string", "enum": [ "recalculate" ] }, "status": { "type": "string" }, "status_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "cell_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "status_url": { "type": "string" } }, "additionalProperties": false }, "CreateTableSheetOperationQueuedResponse": { "type": "object", "title": "CreateTableSheetOperationQueuedResponse", "required": [ "success", "operation", "operation_id", "execution_id", "execution_ids", "cell_count", "version", "status_url", "virtual_cell_count", "cells" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "operation": { "type": "string", "enum": [ "recalculate" ] }, "operation_id": { "type": "string" }, "execution_id": { "type": "string" }, "execution_ids": { "type": "array", "items": { "type": "string" } }, "cell_count": { "type": "integer" }, "version": { "type": "integer" }, "status_url": { "type": "string" }, "virtual_cell_count": { "type": "integer" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/TableCell" } } }, "additionalProperties": false }, "CreateTableSheetOperationNoopResponse": { "type": "object", "title": "CreateTableSheetOperationNoopResponse", "required": [ "success", "cell_count", "virtual_cell_count", "cells" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "cell_count": { "type": "integer", "enum": [ 0 ] }, "virtual_cell_count": { "type": "integer" }, "cells": { "type": "array", "items": { "$ref": "#/components/schemas/TableCell" } } }, "additionalProperties": false }, "CreateTableSheetOperationConfirmationResponse": { "type": "object", "title": "CreateTableSheetOperationConfirmationResponse", "required": [ "success", "requires_confirmation", "confirmation_token", "affected_cell_count", "message" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "requires_confirmation": { "type": "boolean", "enum": [ true ] }, "confirmation_token": { "type": "string" }, "affected_cell_count": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": false }, "TableSheetScoreColumn": { "type": "object", "title": "TableSheetScoreColumn", "required": [ "column_id", "title", "score", "included_count", "excluded_count" ], "properties": { "column_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "score": { "type": "number", "nullable": true }, "included_count": { "type": "integer" }, "excluded_count": { "type": "integer" }, "resolved_scoring_type": { "type": "string", "enum": [ "auto", "boolean", "numeric", "custom", null ], "nullable": true } }, "additionalProperties": false }, "TableSheetScoreCellObject": { "type": "object", "title": "TableSheetScoreCellObject", "required": [ "value" ], "properties": { "value": { "nullable": true }, "positive_metric": { "type": "boolean", "nullable": true } }, "additionalProperties": true }, "TableSheetScoreMetric": { "type": "object", "title": "TableSheetScoreMetric", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "positive_metric": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "TableSheetScoreConfiguration": { "type": "object", "title": "TableSheetScoreConfiguration", "required": [ "score_type", "score_config" ], "properties": { "score_type": { "type": "string", "enum": [ "auto", "boolean", "numeric", "custom" ] }, "score_config": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "TableSheetVersion": { "type": "object", "title": "TableSheetVersion", "required": [ "id", "sheet_id", "version_number" ], "properties": { "id": { "type": "string", "format": "uuid" }, "sheet_id": { "type": "string", "format": "uuid" }, "version_number": { "type": "integer", "description": "Sequential saved version number for this sheet." }, "name": { "type": "string", "nullable": true }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "deltas": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "snapshot": { "type": "object", "additionalProperties": true }, "score": { "type": "object", "additionalProperties": true }, "score_configuration": { "type": "object", "nullable": true, "additionalProperties": true } }, "additionalProperties": true }, "PublicListPagination": { "type": "object", "title": "PublicListPagination", "required": [ "next_cursor", "prev_cursor", "has_more", "limit" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque cursor to pass as cursor for the next page, or null when there is no next page. The cursor is valid only with the same sort, order, and filter parameters used to produce it." }, "prev_cursor": { "type": "string", "nullable": true, "description": "Reserved for previous-page cursors. Public table list endpoints currently return null." }, "has_more": { "type": "boolean", "description": "Whether another page is available." }, "limit": { "type": "integer", "description": "Requested page size." } }, "additionalProperties": false, "description": "Cursor pagination metadata for public table list endpoints. Cursors are opaque and include the active sort, order, cursor value, and a hash of the active filter set." }, "EmptyPublicFilters": { "type": "object", "title": "EmptyPublicFilters", "description": "This endpoint does not echo any filter fields.", "maxProperties": 0, "additionalProperties": false }, "TableCell": { "type": "object", "title": "TableCell", "required": [ "id", "sheet_id", "column_id", "row_index", "status" ], "properties": { "id": { "type": "string", "description": "Cell UUID, or a virtual cell ID for not-yet-computed output cells." }, "sheet_id": { "type": "string", "format": "uuid" }, "execution_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Execution ID associated with the current or most recent computed value, when available." }, "column_id": { "type": "string", "format": "uuid" }, "row_index": { "type": "integer" }, "last_computed_version": { "type": "integer", "nullable": true, "description": "Sheet version_count when this cell was last computed. Null for text cells, virtual cells, or cells that have not completed computation." }, "status": { "type": "string", "enum": [ "STALE", "QUEUED", "DISPATCHED", "RUNNING", "COMPLETED", "FAILED" ] }, "display_value": { "type": "string", "nullable": true }, "input_hash": { "type": "string", "nullable": true }, "value": { "nullable": true, "description": "Structured cell value. Shape depends on the column type." }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "DerivedRatioInsightSpec": { "type": "object", "title": "DerivedRatioInsightSpec", "description": "A display-only derived insight computed as a ratio of two series totals.", "required": [ "label", "numeratorSeriesKey", "denominatorSeriesKey" ], "properties": { "type": { "type": "string", "enum": [ "ratio" ], "default": "ratio" }, "label": { "type": "string", "description": "Label shown for this insight (max 200 chars)." }, "numeratorSeriesKey": { "type": "string", "description": "Key of the numerator series (must match a series key in the chart)." }, "denominatorSeriesKey": { "type": "string", "description": "Key of the denominator series (must match a series key in the chart)." } } }, "DerivedRatioInsightResult": { "type": "object", "title": "DerivedRatioInsightResult", "description": "A computed ratio insight in the response.", "properties": { "type": { "type": "string", "enum": [ "ratio" ] }, "label": { "type": "string" }, "numeratorSeriesKey": { "type": "string" }, "denominatorSeriesKey": { "type": "string" }, "value": { "type": "number", "description": "Ratio of numerator total to denominator total." } } }, "CustomAnalyticsSpec": { "type": "object", "title": "CustomAnalyticsSpec", "description": "Definition for a single custom analytics query.", "required": [ "id", "chartType" ], "properties": { "id": { "type": "string", "description": "Stable identifier for this chart in the response (alphanumeric, hyphens, underscores; max 64 chars). Must be unique within the request." }, "title": { "type": "string", "nullable": true, "description": "Optional display title (max 200 chars). Defaults to id." }, "chartType": { "type": "string", "enum": [ "bar", "line", "area" ], "description": "Chart visualization type. Overall aggregate charts (no timeSeries, no groupByField) must use `bar`." }, "metric": { "type": "string", "nullable": true, "enum": [ "count", "sum", "avg", "min", "max", "percentile" ], "description": "Aggregation function. Omit when using `series` (multi-series mode)." }, "metricField": { "type": "string", "nullable": true, "enum": [ "input_tokens", "output_tokens", "cost", "latency_ms", "prompt_version_number", "turn_count", "tool_call_count", "cached_tokens", "thinking_tokens" ], "description": "Numeric field to aggregate. Required unless metric is `count` or using multi-series mode." }, "percentile": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Required when metric is `percentile`." }, "series": { "type": "array", "nullable": true, "description": "Multi-series mode: define two or more series. Omit metric/metricField/percentile when using this.", "items": { "$ref": "#/components/schemas/CustomAnalyticsSeriesSpec" } }, "derivedInsights": { "type": "array", "nullable": true, "description": "Ratio insights computed from series totals. Only valid in multi-series mode.", "items": { "$ref": "#/components/schemas/DerivedRatioInsightSpec" } }, "groupByField": { "type": "string", "nullable": true, "enum": [ "engine", "provider_type", "prompt_id", "prompt_version_number", "status", "error_type", "tags", "metadata_keys", "output_keys", "input_variable_keys", "tool_names" ], "description": "Break results down by this request log field. Cannot be combined with groupByMetadataKey." }, "groupByMetadataKey": { "type": "string", "nullable": true, "description": "Break results down by the values of this metadata key. Cannot be combined with groupByField." }, "timeSeries": { "type": "boolean", "default": false, "description": "When true, bucket results over time (bucket size chosen automatically from the filter range)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of group-by buckets to return." } } }, "CustomAnalyticsSeriesSpec": { "type": "object", "title": "CustomAnalyticsSeriesSpec", "description": "One series in a multi-series custom analytics query.", "required": [ "key", "label", "metric", "metricField" ], "properties": { "key": { "type": "string", "description": "Unique identifier for this series within the chart (alphanumeric, hyphens, underscores; max 64 chars)." }, "label": { "type": "string", "description": "Human-readable series label shown in chart legends (max 120 chars)." }, "metric": { "type": "string", "enum": [ "sum", "avg", "min", "max", "percentile" ], "description": "Aggregation function for this series." }, "metricField": { "type": "string", "enum": [ "input_tokens", "output_tokens", "cost", "latency_ms", "prompt_version_number", "turn_count", "tool_call_count", "cached_tokens", "thinking_tokens" ], "description": "Numeric field to aggregate." }, "percentile": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Required when metric is `percentile`; omit otherwise." } } }, "CustomAnalyticsSeriesMeta": { "type": "object", "title": "CustomAnalyticsSeriesMeta", "description": "Metadata describing one series in a custom analytics query response.", "properties": { "key": { "type": "string", "description": "Series key (matches keys in each data row)." }, "label": { "type": "string", "description": "Human-readable label." }, "unit": { "type": "string", "enum": [ "count", "tokens", "currency", "duration_seconds", "number" ], "description": "Unit hint for rendering axes." } } }, "CustomAnalyticsResult": { "type": "object", "title": "CustomAnalyticsResult", "description": "Computed result for a single custom analytics query.", "properties": { "id": { "type": "string", "description": "Echoes the chart id from the request." }, "title": { "type": "string", "description": "Chart title (echoed from request, or defaults to id)." }, "chartType": { "type": "string", "enum": [ "bar", "line", "area" ] }, "series": { "type": "array", "description": "Series descriptors (one entry per series). For single-metric charts the only entry has key `value`.", "items": { "$ref": "#/components/schemas/CustomAnalyticsSeriesMeta" } }, "data": { "type": "array", "description": "Rows of chart data. Each row has a `label` string and one numeric key per series. Time-series rows also include `bucketKey` (ISO date string).", "items": { "type": "object", "additionalProperties": true } }, "derivedInsights": { "type": "array", "nullable": true, "description": "Computed ratio insights (multi-series charts only).", "items": { "$ref": "#/components/schemas/DerivedRatioInsightResult" } } } }, "RequestAnalyticsCustomAnalyticsQuery": { "type": "object", "title": "RequestAnalyticsCustomAnalyticsQuery", "description": "Request body for POST /api/public/v2/requests/analytics/custom-analytics. Inherits all filter fields from RequestLogQuery and adds `customCharts`.", "required": [ "customCharts" ], "properties": { "filter_group": { "nullable": true, "description": "Nested filter group with AND/OR logic.", "$ref": "#/components/schemas/StructuredFilterGroup" }, "q": { "type": "string", "nullable": true, "description": "Free-text search query." }, "sort_by": { "type": "string", "nullable": true, "enum": [ "request_start_time", "input_tokens", "output_tokens", "cost", "latency_ms", "status" ], "description": "Accepted for compatibility; does not affect aggregated output." }, "sort_order": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ] }, "customCharts": { "type": "array", "minItems": 1, "description": "One or more chart definitions to compute. Chart ids must be unique.", "items": { "$ref": "#/components/schemas/CustomAnalyticsSpec" } } }, "example": { "filter_group": { "logic": "AND", "filters": [ { "field": "request_start_time", "operator": "between", "value": [ "2025-06-01T00:00:00Z", "2025-06-08T00:00:00Z" ] } ] }, "customCharts": [ { "id": "cost_by_model", "title": "Cost by Model", "chartType": "bar", "metric": "sum", "metricField": "cost", "groupByField": "engine" }, { "id": "requests_over_time", "title": "Requests Over Time", "chartType": "line", "metric": "count", "timeSeries": true } ] } }, "RequestAnalyticsCustomAnalyticsResponse": { "type": "object", "title": "RequestAnalyticsCustomAnalyticsResponse", "required": [ "success", "customCharts" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "customCharts": { "type": "array", "description": "Results in the same order as the input `customCharts` array.", "items": { "$ref": "#/components/schemas/CustomAnalyticsResult" } } } } }, "responses": { "UnauthorizedError": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenError": { "description": "Forbidden - API key does not have access to the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Validation error - request parameters or body are invalid.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HTTPValidationError" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "NotFoundError": { "description": "Not found - requested resource does not exist or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequestsError": { "description": "Too many requests - the endpoint rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimited": { "summary": "Rate limited", "value": { "success": false, "message": "Rate limit exceeded. Please retry later." } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }