--- title: "Prompt Canvas" method: POST path: "/api/v1/prompts/canvas" tags: ["prompts"] --- # Prompt Canvas `POST /api/v1/prompts/canvas` ## Request body - PlaygroundPromptCanvasPayload - `messages` union[], required - union - AIMessage — Message from an AI. An `AIMessage` is returned from a chat model as a response to a prompt. This message represents the output of the model and consists of both the raw output as returned by the model and standardized fields (e.g., tool calls, usage metadata) added by the LangChain framework. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'ai' - `name` string, nullable - `id` string, nullable - `tool_calls` ToolCall[] - `name` string, required - `args` object, required - `id` string, nullable, required - `type` 'tool_call' - `invalid_tool_calls` InvalidToolCall[] - `type` 'invalid_tool_call', required - `id` string, nullable, required - `name` string, nullable, required - `args` string, nullable, required - `error` string, nullable, required - `index` union - integer - string - `extras` object - `usage_metadata` UsageMetadata — Usage metadata for a message, such as token counts. This is a standard representation of token usage that is consistent across models. Example: ```python { "input_tokens": 350, "output_tokens": 240, "total_tokens": 590, "input_token_details": { "audio": 10, "cache_creation": 200, "cache_read": 100, }, "output_token_details": { "audio": 10, "reasoning": 200, }, } ``` !!! warning "Behavior changed in `langchain-core` 0.3.9" Added `input_token_details` and `output_token_details`. !!! note "LangSmith SDK" The LangSmith SDK also has a `UsageMetadata` class. While the two share fields, LangSmith's `UsageMetadata` has additional fields to capture cost information used by the LangSmith platform. - `input_tokens` integer, required - `output_tokens` integer, required - `total_tokens` integer, required - `input_token_details` InputTokenDetails — Breakdown of input token counts. Does *not* need to sum to full input token count. Does *not* need to have all keys. Example: ```python { "audio": 10, "cache_creation": 200, "cache_read": 100, } ``` May also hold extra provider-specific keys. !!! version-added "Added in `langchain-core` 0.3.9" - `audio` integer - `cache_creation` integer - `cache_read` integer - `output_token_details` OutputTokenDetails — Breakdown of output token counts. Does *not* need to sum to full output token count. Does *not* need to have all keys. Example: ```python { "audio": 10, "reasoning": 200, } ``` May also hold extra provider-specific keys. !!! version-added "Added in `langchain-core` 0.3.9" - `audio` integer - `reasoning` integer - HumanMessage — Message from the user. A `HumanMessage` is a message that is passed in from a user to the model. Example: ```python from langchain_core.messages import HumanMessage, SystemMessage messages = [ SystemMessage(content="You are a helpful assistant! Your name is Bob."), HumanMessage(content="What is your name?"), ] # Instantiate a chat model and invoke it with the messages model = ... print(model.invoke(messages)) ``` - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'human' - `name` string, nullable - `id` string, nullable - ChatMessage — Message that can be assigned an arbitrary speaker (i.e. role). - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'chat' - `name` string, nullable - `id` string, nullable - `role` string, required - SystemMessage — Message for priming AI behavior. The system message is usually passed in as the first of a sequence of input messages. Example: ```python from langchain_core.messages import HumanMessage, SystemMessage messages = [ SystemMessage(content="You are a helpful assistant! Your name is Bob."), HumanMessage(content="What is your name?"), ] # Define a chat model and invoke it with the messages print(model.invoke(messages)) ``` - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'system' - `name` string, nullable - `id` string, nullable - FunctionMessage — Message for passing the result of executing a tool back to a model. `FunctionMessage` are an older version of the `ToolMessage` schema, and do not contain the `tool_call_id` field. The `tool_call_id` field is used to associate the tool call request with the tool call response. Useful in situations where a chat model is able to request multiple tool calls in parallel. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'function' - `name` string, required - `id` string, nullable - ToolMessage — Message for passing the result of executing a tool back to a model. `ToolMessage` objects contain the result of a tool invocation. Typically, the result is encoded inside the `content` field. `tool_call_id` is used to associate the tool call request with the tool call response. Useful in situations where a chat model is able to request multiple tool calls in parallel. Example: A `ToolMessage` representing a result of `42` from a tool call with id ```python from langchain_core.messages import ToolMessage ToolMessage(content="42", tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL") ``` Example: A `ToolMessage` where only part of the tool output is sent to the model and the full output is passed in to artifact. ```python from langchain_core.messages import ToolMessage tool_output = { "stdout": "From the graph we can see that the correlation between " "x and y is ...", "stderr": None, "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."}, } ToolMessage( content=tool_output["stdout"], artifact=tool_output, tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL", ) ``` - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'tool' - `name` string, nullable - `id` string, nullable - `tool_call_id` string, required - `artifact` unknown - `status` 'success' | 'error' - AIMessageChunk — Message chunk from an AI (yielded when streaming). - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'AIMessageChunk' - `name` string, nullable - `id` string, nullable - `tool_calls` ToolCall[] - `name` string, required - `args` object, required - `id` string, nullable, required - `type` 'tool_call' - `invalid_tool_calls` InvalidToolCall[] - `type` 'invalid_tool_call', required - `id` string, nullable, required - `name` string, nullable, required - `args` string, nullable, required - `error` string, nullable, required - `index` union - integer - string - `extras` object - `usage_metadata` UsageMetadata — Usage metadata for a message, such as token counts. This is a standard representation of token usage that is consistent across models. Example: ```python { "input_tokens": 350, "output_tokens": 240, "total_tokens": 590, "input_token_details": { "audio": 10, "cache_creation": 200, "cache_read": 100, }, "output_token_details": { "audio": 10, "reasoning": 200, }, } ``` !!! warning "Behavior changed in `langchain-core` 0.3.9" Added `input_token_details` and `output_token_details`. !!! note "LangSmith SDK" The LangSmith SDK also has a `UsageMetadata` class. While the two share fields, LangSmith's `UsageMetadata` has additional fields to capture cost information used by the LangSmith platform. - `input_tokens` integer, required - `output_tokens` integer, required - `total_tokens` integer, required - `input_token_details` InputTokenDetails — Breakdown of input token counts. Does *not* need to sum to full input token count. Does *not* need to have all keys. Example: ```python { "audio": 10, "cache_creation": 200, "cache_read": 100, } ``` May also hold extra provider-specific keys. !!! version-added "Added in `langchain-core` 0.3.9" - `audio` integer - `cache_creation` integer - `cache_read` integer - `output_token_details` OutputTokenDetails — Breakdown of output token counts. Does *not* need to sum to full output token count. Does *not* need to have all keys. Example: ```python { "audio": 10, "reasoning": 200, } ``` May also hold extra provider-specific keys. !!! version-added "Added in `langchain-core` 0.3.9" - `audio` integer - `reasoning` integer - `tool_call_chunks` ToolCallChunk[] - `name` string, nullable, required - `args` string, nullable, required - `id` string, nullable, required - `index` integer, nullable, required - `type` 'tool_call_chunk' - `chunk_position` 'last', nullable - HumanMessageChunk — Human Message chunk. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'HumanMessageChunk' - `name` string, nullable - `id` string, nullable - ChatMessageChunk — Chat Message chunk. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'ChatMessageChunk' - `name` string, nullable - `id` string, nullable - `role` string, required - SystemMessageChunk — System Message chunk. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'SystemMessageChunk' - `name` string, nullable - `id` string, nullable - FunctionMessageChunk — Function Message chunk. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'FunctionMessageChunk' - `name` string, required - `id` string, nullable - ToolMessageChunk — Tool Message chunk. - `content` union, required - string - union[] - union - … - `additional_kwargs` object - `response_metadata` object - `type` 'ToolMessageChunk' - `name` string, nullable - `id` string, nullable - `tool_call_id` string, required - `artifact` unknown - `status` 'success' | 'error' - `highlighted` Highlight - `prompt_chunk_start_index` integer, required - `prompt_chunk_end_index` integer, required - `prompt_chunk` string, required - `highlight_text` string, required - `artifact` Artifact - `id` string, required - `contents` ArtifactContent[], required - `index` integer, required - `content` string, required - `current_content_index` integer, required - `artifact_length` 'shortest' | 'short' | 'long' | 'longest', nullable - `reading_level` 'child' | 'teenager' | 'college' | 'phd', nullable - `custom_action` string, nullable - `template_format` 'f-string' | 'mustache', required - `secrets` object, required ## Response `200` Successful Response - unknown ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/langchain-ai/apis/langsmith.md) · [All operations](https://skmtc.net/langchain-ai/apis/langsmith/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langchain-ai/langsmith/revisions/a0acb3a6a101/schema)