diff --git a/en/cli/resources/beta/subresources/threads/index.md b/en/cli/resources/beta/subresources/threads/index.md index 54d38b82..857e2f23 100644 --- a/en/cli/resources/beta/subresources/threads/index.md +++ b/en/cli/resources/beta/subresources/threads/index.md @@ -6,7 +6,7 @@ **post** `/threads` -Create thread +Create a thread. ### Parameters @@ -108,7 +108,7 @@ openai beta:threads create \ **post** `/threads/runs` -Create thread and run +Create a thread and run it in one request. ### Parameters @@ -176,7 +176,7 @@ Create thread and run A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. -- `--tool: optional array of unknown` +- `--tool: optional array of AssistantTool` Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. @@ -396,7 +396,27 @@ Create thread and run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -440,10 +460,76 @@ Create thread and run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -536,11 +622,13 @@ openai beta:threads create-and-run \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -562,7 +650,7 @@ openai beta:threads create-and-run \ **get** `/threads/{thread_id}` -Retrieve thread +Retrieves a thread. ### Parameters @@ -652,7 +740,7 @@ openai beta:threads retrieve \ **post** `/threads/{thread_id}` -Modify thread +Modifies a thread. ### Parameters @@ -755,7 +843,7 @@ openai beta:threads update \ **delete** `/threads/{thread_id}` -Delete thread +Delete a thread. ### Parameters @@ -995,7 +1083,7 @@ openai beta:threads delete \ **get** `/threads/{thread_id}/runs` -List runs +Returns a list of runs belonging to a thread. ### Parameters @@ -1225,7 +1313,27 @@ List runs The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -1269,10 +1377,76 @@ List runs The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -1375,11 +1549,13 @@ openai beta:threads:runs list \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -1407,7 +1583,7 @@ openai beta:threads:runs list \ **post** `/threads/{thread_id}/runs` -Create run +Create a run. ### Parameters @@ -1494,7 +1670,7 @@ Create run `required` means the model must call one or more tools before responding to the user. Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. -- `--tool: optional array of unknown` +- `--tool: optional array of AssistantTool` Body param: Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. @@ -1714,7 +1890,27 @@ Create run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -1758,10 +1954,76 @@ Create run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -1855,11 +2117,13 @@ openai beta:threads:runs create \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -1881,7 +2145,7 @@ openai beta:threads:runs create \ **get** `/threads/{thread_id}/runs/{run_id}` -Retrieve run +Retrieves a run. ### Parameters @@ -2099,7 +2363,27 @@ Retrieve run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -2143,64 +2427,130 @@ Retrieve run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `truncation_strategy: object { type, last_messages }` + - `code_interpreter_tool: object { type }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: "code_interpreter"` - - `type: "auto" or "last_messages"` + The type of tool being defined: `code_interpreter` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `file_search_tool: object { type, file_search }` - - `"auto"` + - `type: "file_search"` - - `"last_messages"` + The type of tool being defined: `file_search` - - `last_messages: optional number` + - `file_search: optional object { max_num_results, ranking_options }` - The number of most recent messages from the thread when constructing the context for the run. + Overrides for the file search tool. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `max_num_results: optional number` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `completion_tokens: number` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Number of completion tokens used over the course of the run. + - `ranking_options: optional object { score_threshold, ranker }` - - `prompt_tokens: number` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - Number of prompt tokens used over the course of the run. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `total_tokens: number` + - `score_threshold: number` - Total number of tokens used (prompt + completion). + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `temperature: optional number` + - `ranker: optional "auto" or "default_2024_08_21"` - The sampling temperature used for this run. If not set, defaults to 1. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `top_p: optional number` + - `"auto"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"default_2024_08_21"` -### Example + - `function_tool: object { function, type }` -```cli -openai beta:threads:runs retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + - `function: object { name, description, parameters, strict }` -#### Response + - `name: string` -```json -{ - "id": "id", + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + + - `truncation_strategy: object { type, last_messages }` + + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + + - `type: "auto" or "last_messages"` + + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + + - `"auto"` + + - `"last_messages"` + + - `last_messages: optional number` + + The number of most recent messages from the thread when constructing the context for the run. + + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + + - `completion_tokens: number` + + Number of completion tokens used over the course of the run. + + - `prompt_tokens: number` + + Number of prompt tokens used over the course of the run. + + - `total_tokens: number` + + Total number of tokens used (prompt + completion). + + - `temperature: optional number` + + The sampling temperature used for this run. If not set, defaults to 1. + + - `top_p: optional number` + + The nucleus sampling value used for this run. If not set, defaults to 1. + +### Example + +```cli +openai beta:threads:runs retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` + +#### Response + +```json +{ + "id": "id", "assistant_id": "assistant_id", "cancelled_at": 0, "completed_at": 0, @@ -2240,11 +2590,13 @@ openai beta:threads:runs retrieve \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -2266,7 +2618,7 @@ openai beta:threads:runs retrieve \ **post** `/threads/{thread_id}/runs/{run_id}` -Modify run +Modifies a run. ### Parameters @@ -2493,7 +2845,27 @@ Modify run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -2537,10 +2909,76 @@ Modify run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -2634,11 +3072,13 @@ openai beta:threads:runs update \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -2660,7 +3100,7 @@ openai beta:threads:runs update \ **post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` -Submit tool outputs to run +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. ### Parameters @@ -2882,7 +3322,27 @@ Submit tool outputs to run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -2926,10 +3386,76 @@ Submit tool outputs to run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -3024,11 +3550,13 @@ openai beta:threads:runs submit-tool-outputs \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -3050,7 +3578,7 @@ openai beta:threads:runs submit-tool-outputs \ **post** `/threads/{thread_id}/runs/{run_id}/cancel` -Cancel a run +Cancels a run that is `in_progress`. ### Parameters @@ -3268,7 +3796,27 @@ Cancel a run The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -3312,60 +3860,126 @@ Cancel a run The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `truncation_strategy: object { type, last_messages }` + - `code_interpreter_tool: object { type }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: "code_interpreter"` - - `type: "auto" or "last_messages"` + The type of tool being defined: `code_interpreter` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `file_search_tool: object { type, file_search }` - - `"auto"` + - `type: "file_search"` - - `"last_messages"` + The type of tool being defined: `file_search` - - `last_messages: optional number` + - `file_search: optional object { max_num_results, ranking_options }` - The number of most recent messages from the thread when constructing the context for the run. + Overrides for the file search tool. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `max_num_results: optional number` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `completion_tokens: number` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Number of completion tokens used over the course of the run. + - `ranking_options: optional object { score_threshold, ranker }` - - `prompt_tokens: number` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - Number of prompt tokens used over the course of the run. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `total_tokens: number` + - `score_threshold: number` - Total number of tokens used (prompt + completion). + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `temperature: optional number` + - `ranker: optional "auto" or "default_2024_08_21"` - The sampling temperature used for this run. If not set, defaults to 1. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `top_p: optional number` + - `"auto"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"default_2024_08_21"` -### Example + - `function_tool: object { function, type }` -```cli -openai beta:threads:runs cancel \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + - `function: object { name, description, parameters, strict }` -#### Response + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + + - `truncation_strategy: object { type, last_messages }` + + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + + - `type: "auto" or "last_messages"` + + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + + - `"auto"` + + - `"last_messages"` + + - `last_messages: optional number` + + The number of most recent messages from the thread when constructing the context for the run. + + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + + - `completion_tokens: number` + + Number of completion tokens used over the course of the run. + + - `prompt_tokens: number` + + Number of prompt tokens used over the course of the run. + + - `total_tokens: number` + + Total number of tokens used (prompt + completion). + + - `temperature: optional number` + + The sampling temperature used for this run. If not set, defaults to 1. + + - `top_p: optional number` + + The nucleus sampling value used for this run. If not set, defaults to 1. + +### Example + +```cli +openai beta:threads:runs cancel \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id +``` + +#### Response ```json { @@ -3409,11 +4023,13 @@ openai beta:threads:runs cancel \ }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -3663,7 +4279,27 @@ openai beta:threads:runs cancel \ The Unix timestamp (in seconds) for when the run was started. - - `status: unknown` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: string` @@ -3707,10 +4343,76 @@ openai beta:threads:runs cancel \ The name of the function to call. - - `tools: array of unknown` + - `tools: array of AssistantTool` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `file_search_tool: object { type, file_search }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `file_search: optional object { max_num_results, ranking_options }` + + Overrides for the file search tool. + + - `max_num_results: optional number` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: optional object { score_threshold, ranker }` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `function_tool: object { function, type }` + + - `function: object { name, description, parameters, strict }` + + - `name: string` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: optional string` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional map[unknown]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: "function"` + + The type of tool being defined: `function` + - `truncation_strategy: object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -3753,7 +4455,27 @@ openai beta:threads:runs cancel \ ### Run Status -- `run_status: unknown` +- `run_status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` # Steps @@ -3763,7 +4485,7 @@ openai beta:threads:runs cancel \ **get** `/threads/{thread_id}/runs/{run_id}/steps` -List run steps +Returns a list of run steps belonging to a run. ### Parameters @@ -3900,238 +4622,143 @@ List run steps Details of the tool call. - - `tool_calls: array of unknown` + - `tool_calls: array of ToolCall` An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: "tool_calls"` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - Always `tool_calls`. + Details of the Code Interpreter tool call the run step was involved in. - - `thread_id: string` + - `id: string` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + The ID of the tool call. - - `type: "message_creation" or "tool_calls"` + - `code_interpreter: object { input, outputs }` - The type of run step, which can be either `message_creation` or `tool_calls`. + The Code Interpreter tool call definition. - - `"message_creation"` + - `input: string` - - `"tool_calls"` + The input to the Code Interpreter tool call. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `outputs: array of object { logs, type } or object { image, type }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `completion_tokens: number` + - `logs: object { logs, type }` - Number of completion tokens used over the course of the run step. + Text output from the Code Interpreter tool call as part of a run step. - - `prompt_tokens: number` + - `logs: string` - Number of prompt tokens used over the course of the run step. + The text output from the Code Interpreter tool call. - - `total_tokens: number` + - `type: "logs"` - Total number of tokens used (prompt + completion). + Always `logs`. - - `first_id: string` + - `image: object { image, type }` - - `has_more: boolean` + - `image: object { file_id }` - - `last_id: string` + - `file_id: string` - - `object: string` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. -### Example + - `type: "image"` -```cli -openai beta:threads:runs:steps list \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --run-id run_id -``` + Always `image`. -#### Response + - `type: "code_interpreter"` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" -} -``` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. -## Retrieve run step + - `file_search_tool_call: object { id, file_search, type }` -`$ openai beta:threads:runs:steps retrieve` + - `id: string` -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` + The ID of the tool call object. -Retrieve run step + - `file_search: object { ranking_options, results }` -### Parameters + For now, this is always going to be an empty object. -- `--thread-id: string` + - `ranking_options: optional object { ranker, score_threshold }` - The ID of the thread to which the run and run step belongs. + The ranking options for the file search. -- `--run-id: string` + - `ranker: "auto" or "default_2024_08_21"` - The ID of the run to which the run step belongs. + The ranker to use for the file search. If not specified will use the `auto` ranker. -- `--step-id: string` - - The ID of the run step to retrieve. - -- `--include: optional array of RunStepInclude` - - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - -### Returns - -- `run_step: object { id, assistant_id, cancelled_at, 13 more }` - - Represents a step in execution of a run. - - - `id: string` - - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run step was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run step completed. - - - `created_at: number` - - The Unix timestamp (in seconds) for when the run step was created. - - - `expired_at: number` - - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - - `failed_at: number` - - The Unix timestamp (in seconds) for when the run step failed. - - - `last_error: object { code, message }` - - The last error associated with this run step. Will be `null` if there are no errors. + - `"auto"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"default_2024_08_21"` - One of `server_error` or `rate_limit_exceeded`. + - `score_threshold: number` - - `"server_error"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"rate_limit_exceeded"` + - `results: optional array of object { file_id, file_name, score, content }` - - `message: string` + The results of the file search. - A human-readable description of the error. + - `file_id: string` - - `metadata: map[string]` + The ID of the file that result was found in. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `file_name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the file that result was found in. - - `object: "thread.run.step"` + - `score: number` - The object type, which is always `thread.run.step`. + The score of the result. All values must be a floating point number between 0 and 1. - - `run_id: string` + - `content: optional array of object { text, type }` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + The content of the result that was found. The content is only included if requested via the include query parameter. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `text: optional string` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + The text content of the file. - - `"in_progress"` + - `type: optional "text"` - - `"cancelled"` + The type of the content. - - `"failed"` + - `"text"` - - `"completed"` + - `type: "file_search"` - - `"expired"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `function_tool_call: object { id, function, type }` - The details of the run step. + - `id: string` - - `message_creation_step_details: object { message_creation, type }` + The ID of the tool call object. - Details of the message creation by the run step. + - `function: object { arguments, name, output }` - - `message_creation: object { message_id }` + The definition of the function that was called. - - `message_id: string` + - `arguments: string` - The ID of the message that was created by this run step. + The arguments passed to the function. - - `type: "message_creation"` + - `name: string` - Always `message_creation`. + The name of the function. - - `tool_calls_step_details: object { tool_calls, type }` + - `output: string` - Details of the tool call. + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `tool_calls: array of unknown` + - `type: "function"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The type of tool call. This is always going to be `function` for this type of tool call. - `type: "tool_calls"` @@ -4165,20 +4792,29 @@ Retrieve run step Total number of tokens used (prompt + completion). + - `first_id: string` + + - `has_more: boolean` + + - `last_id: string` + + - `object: string` + ### Example ```cli -openai beta:threads:runs:steps retrieve \ +openai beta:threads:runs:steps list \ --api-key 'My API Key' \ --thread-id thread_id \ - --run-id run_id \ - --step-id step_id + --run-id run_id ``` #### Response ```json { + "data": [ + { "id": "id", "assistant_id": "assistant_id", "cancelled_at": 0, @@ -4209,162 +4845,199 @@ openai beta:threads:runs:steps retrieve \ "prompt_tokens": 0, "total_tokens": 0 } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" } ``` -## Domain Types +## Retrieve run step -### Code Interpreter Logs +`$ openai beta:threads:runs:steps retrieve` -- `code_interpreter_logs: object { index, type, logs }` +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` - Text output from the Code Interpreter tool call as part of a run step. +Retrieves a run step. - - `index: number` +### Parameters - The index of the output in the outputs array. +- `--thread-id: string` - - `type: "logs"` + The ID of the thread to which the run and run step belongs. - Always `logs`. +- `--run-id: string` - - `logs: optional string` + The ID of the run to which the run step belongs. - The text output from the Code Interpreter tool call. +- `--step-id: string` -### Code Interpreter Output Image + The ID of the run step to retrieve. -- `code_interpreter_output_image: object { index, type, image }` +- `--include: optional array of RunStepInclude` - - `index: number` + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - The index of the output in the outputs array. + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "image"` +### Returns - Always `image`. +- `run_step: object { id, assistant_id, cancelled_at, 13 more }` - - `image: optional object { file_id }` + Represents a step in execution of a run. - - `file_id: optional string` + - `id: string` - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + The identifier of the run step, which can be referenced in API endpoints. -### Code Interpreter Tool Call + - `assistant_id: string` -- `code_interpreter_tool_call: object { id, code_interpreter, type }` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - Details of the Code Interpreter tool call the run step was involved in. + - `cancelled_at: number` - - `id: string` + The Unix timestamp (in seconds) for when the run step was cancelled. - The ID of the tool call. + - `completed_at: number` - - `code_interpreter: object { input, outputs }` + The Unix timestamp (in seconds) for when the run step completed. - The Code Interpreter tool call definition. + - `created_at: number` - - `input: string` + The Unix timestamp (in seconds) for when the run step was created. - The input to the Code Interpreter tool call. + - `expired_at: number` - - `outputs: array of object { logs, type } or object { image, type }` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `failed_at: number` - - `logs: object { logs, type }` + The Unix timestamp (in seconds) for when the run step failed. - Text output from the Code Interpreter tool call as part of a run step. + - `last_error: object { code, message }` - - `logs: string` + The last error associated with this run step. Will be `null` if there are no errors. - The text output from the Code Interpreter tool call. + - `code: "server_error" or "rate_limit_exceeded"` - - `type: "logs"` + One of `server_error` or `rate_limit_exceeded`. - Always `logs`. + - `"server_error"` - - `image: object { image, type }` + - `"rate_limit_exceeded"` - - `image: object { file_id }` + - `message: string` - - `file_id: string` + A human-readable description of the error. - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `metadata: map[string]` - - `type: "image"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - Always `image`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "code_interpreter"` + - `object: "thread.run.step"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The object type, which is always `thread.run.step`. -### Code Interpreter Tool Call Delta + - `run_id: string` -- `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - Details of the Code Interpreter tool call the run step was involved in. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `index: number` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The index of the tool call in the tool calls array. + - `"in_progress"` - - `type: "code_interpreter"` + - `"cancelled"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"failed"` - - `id: optional string` + - `"completed"` - The ID of the tool call. + - `"expired"` - - `code_interpreter: optional object { input, outputs }` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - The Code Interpreter tool call definition. + The details of the run step. - - `input: optional string` + - `message_creation_step_details: object { message_creation, type }` - The input to the Code Interpreter tool call. + Details of the message creation by the run step. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `message_creation: object { message_id }` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `message_id: string` - - `code_interpreter_logs: object { index, type, logs }` + The ID of the message that was created by this run step. + + - `type: "message_creation"` + + Always `message_creation`. + + - `tool_calls_step_details: object { tool_calls, type }` + + Details of the tool call. + + - `tool_calls: array of ToolCall` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `code_interpreter_tool_call: object { id, code_interpreter, type }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `id: string` + + The ID of the tool call. + + - `code_interpreter: object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: string` + + The input to the Code Interpreter tool call. + + - `outputs: array of object { logs, type } or object { image, type }` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `logs: object { logs, type }` Text output from the Code Interpreter tool call as part of a run step. - - `index: number` + - `logs: string` - The index of the output in the outputs array. + The text output from the Code Interpreter tool call. - `type: "logs"` Always `logs`. - - `logs: optional string` - - The text output from the Code Interpreter tool call. + - `image: object { image, type }` - - `code_interpreter_output_image: object { index, type, image }` + - `image: object { file_id }` - - `index: number` + - `file_id: string` - The index of the output in the outputs array. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - `type: "image"` Always `image`. - - `image: optional object { file_id }` - - - `file_id: optional string` - - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + - `type: "code_interpreter"` -### File Search Tool Call + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. -- `file_search_tool_call: object { id, file_search, type }` + - `file_search_tool_call: object { id, file_search, type }` - `id: string` @@ -4424,29 +5097,7 @@ openai beta:threads:runs:steps retrieve \ The type of tool call. This is always going to be `file_search` for this type of tool call. -### File Search Tool Call Delta - -- `file_search_tool_call_delta: object { file_search, index, type, id }` - - - `file_search: unknown` - - For now, this is always going to be an empty object. - - - `index: number` - - The index of the tool call in the tool calls array. - - - `type: "file_search"` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `id: optional string` - - The ID of the tool call object. - -### Function Tool Call - -- `function_tool_call: object { id, function, type }` + - `function_tool_call: object { id, function, type }` - `id: string` @@ -4472,693 +5123,3205 @@ openai beta:threads:runs:steps retrieve \ The type of tool call. This is always going to be `function` for this type of tool call. -### Function Tool Call Delta + - `type: "tool_calls"` -- `function_tool_call_delta: object { index, type, id, function }` + Always `tool_calls`. - - `index: number` + - `thread_id: string` - The index of the tool call in the tool calls array. + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - `type: "function"` + - `type: "message_creation" or "tool_calls"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `id: optional string` + - `"message_creation"` - The ID of the tool call object. + - `"tool_calls"` - - `function: optional object { arguments, name, output }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The definition of the function that was called. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `arguments: optional string` + - `completion_tokens: number` - The arguments passed to the function. + Number of completion tokens used over the course of the run step. - - `name: optional string` + - `prompt_tokens: number` - The name of the function. + Number of prompt tokens used over the course of the run step. - - `output: optional string` + - `total_tokens: number` - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + Total number of tokens used (prompt + completion). -### Message Creation Step Details +### Example -- `message_creation_step_details: object { message_creation, type }` +```cli +openai beta:threads:runs:steps retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --run-id run_id \ + --step-id step_id +``` - Details of the message creation by the run step. +#### Response - - `message_creation: object { message_id }` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` - - `message_id: string` +## Domain Types - The ID of the message that was created by this run step. +### Code Interpreter Logs - - `type: "message_creation"` +- `code_interpreter_logs: object { index, type, logs }` - Always `message_creation`. + Text output from the Code Interpreter tool call as part of a run step. -### Run Step + - `index: number` -- `run_step: object { id, assistant_id, cancelled_at, 13 more }` + The index of the output in the outputs array. - Represents a step in execution of a run. + - `type: "logs"` - - `id: string` + Always `logs`. - The identifier of the run step, which can be referenced in API endpoints. + - `logs: optional string` - - `assistant_id: string` + The text output from the Code Interpreter tool call. - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. +### Code Interpreter Output Image - - `cancelled_at: number` +- `code_interpreter_output_image: object { index, type, image }` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `index: number` - - `completed_at: number` + The index of the output in the outputs array. - The Unix timestamp (in seconds) for when the run step completed. + - `type: "image"` - - `created_at: number` + Always `image`. - The Unix timestamp (in seconds) for when the run step was created. + - `image: optional object { file_id }` - - `expired_at: number` + - `file_id: optional string` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `failed_at: number` +### Code Interpreter Tool Call - The Unix timestamp (in seconds) for when the run step failed. +- `code_interpreter_tool_call: object { id, code_interpreter, type }` - - `last_error: object { code, message }` + Details of the Code Interpreter tool call the run step was involved in. - The last error associated with this run step. Will be `null` if there are no errors. + - `id: string` - - `code: "server_error" or "rate_limit_exceeded"` + The ID of the tool call. - One of `server_error` or `rate_limit_exceeded`. + - `code_interpreter: object { input, outputs }` - - `"server_error"` + The Code Interpreter tool call definition. - - `"rate_limit_exceeded"` + - `input: string` - - `message: string` + The input to the Code Interpreter tool call. - A human-readable description of the error. + - `outputs: array of object { logs, type } or object { image, type }` - - `metadata: map[string]` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `logs: object { logs, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Text output from the Code Interpreter tool call as part of a run step. - - `object: "thread.run.step"` + - `logs: string` - The object type, which is always `thread.run.step`. + The text output from the Code Interpreter tool call. - - `run_id: string` + - `type: "logs"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. + Always `logs`. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `image: object { image, type }` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `image: object { file_id }` - - `"in_progress"` + - `file_id: string` - - `"cancelled"` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `"failed"` + - `type: "image"` - - `"completed"` + Always `image`. - - `"expired"` + - `type: "code_interpreter"` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The details of the run step. +### Code Interpreter Tool Call Delta - - `message_creation_step_details: object { message_creation, type }` +- `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` - Details of the message creation by the run step. + Details of the Code Interpreter tool call the run step was involved in. - - `message_creation: object { message_id }` + - `index: number` - - `message_id: string` + The index of the tool call in the tool calls array. - The ID of the message that was created by this run step. + - `type: "code_interpreter"` - - `type: "message_creation"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Always `message_creation`. + - `id: optional string` - - `tool_calls_step_details: object { tool_calls, type }` + The ID of the tool call. - Details of the tool call. + - `code_interpreter: optional object { input, outputs }` - - `tool_calls: array of unknown` + The Code Interpreter tool call definition. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `input: optional string` - - `type: "tool_calls"` + The input to the Code Interpreter tool call. - Always `tool_calls`. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `thread_id: string` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `code_interpreter_logs: object { index, type, logs }` - - `type: "message_creation" or "tool_calls"` + Text output from the Code Interpreter tool call as part of a run step. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `index: number` - - `"message_creation"` + The index of the output in the outputs array. - - `"tool_calls"` + - `type: "logs"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + Always `logs`. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `logs: optional string` - - `completion_tokens: number` + The text output from the Code Interpreter tool call. - Number of completion tokens used over the course of the run step. + - `code_interpreter_output_image: object { index, type, image }` - - `prompt_tokens: number` + - `index: number` - Number of prompt tokens used over the course of the run step. + The index of the output in the outputs array. - - `total_tokens: number` + - `type: "image"` - Total number of tokens used (prompt + completion). + Always `image`. -### Run Step Delta + - `image: optional object { file_id }` -- `run_step_delta: unknown` + - `file_id: optional string` -### Run Step Delta Event + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. -- `run_step_delta_event: object { id, delta, object }` +### File Search Tool Call - Represents a run step delta i.e. any changed fields on a run step during streaming. +- `file_search_tool_call: object { id, file_search, type }` - `id: string` - The identifier of the run step, which can be referenced in API endpoints. + The ID of the tool call object. - - `delta: unknown` + - `file_search: object { ranking_options, results }` - - `object: "thread.run.step.delta"` + For now, this is always going to be an empty object. - The object type, which is always `thread.run.step.delta`. + - `ranking_options: optional object { ranker, score_threshold }` -### Run Step Delta Message Delta + The ranking options for the file search. -- `run_step_delta_message_delta: object { type, message_creation }` + - `ranker: "auto" or "default_2024_08_21"` - Details of the message creation by the run step. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `type: "message_creation"` + - `"auto"` - Always `message_creation`. + - `"default_2024_08_21"` - - `message_creation: optional object { message_id }` + - `score_threshold: number` - - `message_id: optional string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The ID of the message that was created by this run step. + - `results: optional array of object { file_id, file_name, score, content }` -### Run Step Include + The results of the file search. -- `run_step_include: "step_details.tool_calls[*].file_search.results[*].content"` + - `file_id: string` - - `"step_details.tool_calls[*].file_search.results[*].content"` + The ID of the file that result was found in. -### Tool Call + - `file_name: string` -- `tool_call: unknown` + The name of the file that result was found in. -### Tool Call Delta + - `score: number` -- `tool_call_delta: unknown` + The score of the result. All values must be a floating point number between 0 and 1. -### Tool Call Delta Object + - `content: optional array of object { text, type }` -- `tool_call_delta_object: object { type, tool_calls }` + The content of the result that was found. The content is only included if requested via the include query parameter. - Details of the tool call. + - `text: optional string` - - `type: "tool_calls"` + The text content of the file. - Always `tool_calls`. + - `type: optional "text"` - - `tool_calls: optional array of unknown` + The type of the content. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `"text"` -### Tool Calls Step Details + - `type: "file_search"` -- `tool_calls_step_details: object { tool_calls, type }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - Details of the tool call. +### File Search Tool Call Delta - - `tool_calls: array of unknown` +- `file_search_tool_call_delta: object { file_search, index, type, id }` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `file_search: unknown` - - `type: "tool_calls"` + For now, this is always going to be an empty object. - Always `tool_calls`. + - `index: number` -# Messages + The index of the tool call in the tool calls array. -## List messages + - `type: "file_search"` -`$ openai beta:threads:messages list` + The type of tool call. This is always going to be `file_search` for this type of tool call. -**get** `/threads/{thread_id}/messages` + - `id: optional string` -List messages + The ID of the tool call object. -### Parameters +### Function Tool Call -- `--thread-id: string` +- `function_tool_call: object { id, function, type }` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) the messages belong to. + - `id: string` -- `--after: optional string` + The ID of the tool call object. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `function: object { arguments, name, output }` -- `--before: optional string` + The definition of the function that was called. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `arguments: string` -- `--limit: optional number` + The arguments passed to the function. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `name: string` -- `--order: optional "asc" or "desc"` + The name of the function. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `output: string` -- `--run-id: optional string` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - Filter messages by the run ID that generated them. + - `type: "function"` -### Returns + The type of tool call. This is always going to be `function` for this type of tool call. -- `ListMessagesResponse: object { data, first_id, has_more, 2 more }` +### Function Tool Call Delta - - `data: array of Message` +- `function_tool_call_delta: object { index, type, id, function }` - - `id: string` + - `index: number` - The identifier, which can be referenced in API endpoints. + The index of the tool call in the tool calls array. - - `assistant_id: string` + - `type: "function"` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The type of tool call. This is always going to be `function` for this type of tool call. - - `attachments: array of object { file_id, tools }` + - `id: optional string` - A list of files attached to the message, and the tools they were added to. + The ID of the tool call object. - - `file_id: optional string` + - `function: optional object { arguments, name, output }` - The ID of the file to attach to the message. + The definition of the function that was called. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `arguments: optional string` - The tools to add this file to. + The arguments passed to the function. - - `code_interpreter_tool: object { type }` + - `name: optional string` - - `type: "code_interpreter"` + The name of the function. - The type of tool being defined: `code_interpreter` + - `output: optional string` - - `AssistantToolsFileSearchTypeOnly: object { type }` + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - `completed_at: number` +### Message Creation Step Details - The Unix timestamp (in seconds) for when the message was completed. +- `message_creation_step_details: object { message_creation, type }` - - `content: array of unknown` + Details of the message creation by the run step. - The content of the message in array of text and/or images. + - `message_creation: object { message_id }` - - `created_at: number` + - `message_id: string` - The Unix timestamp (in seconds) for when the message was created. + The ID of the message that was created by this run step. - - `incomplete_at: number` + - `type: "message_creation"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Always `message_creation`. - - `incomplete_details: object { reason }` +### Run Step - On an incomplete message, details about why the message is incomplete. +- `run_step: object { id, assistant_id, cancelled_at, 13 more }` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + Represents a step in execution of a run. - The reason the message is incomplete. + - `id: string` - - `"content_filter"` + The identifier of the run step, which can be referenced in API endpoints. - - `"max_tokens"` + - `assistant_id: string` - - `"run_cancelled"` + The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - `"run_expired"` + - `cancelled_at: number` - - `"run_failed"` + The Unix timestamp (in seconds) for when the run step was cancelled. - - `metadata: map[string]` + - `completed_at: number` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The Unix timestamp (in seconds) for when the run step completed. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `created_at: number` - - `object: "thread.message"` + The Unix timestamp (in seconds) for when the run step was created. - The object type, which is always `thread.message`. + - `expired_at: number` - - `role: "user" or "assistant"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The entity that produced the message. One of `user` or `assistant`. + - `failed_at: number` - - `"user"` + The Unix timestamp (in seconds) for when the run step failed. - - `"assistant"` + - `last_error: object { code, message }` - - `run_id: string` + The last error associated with this run step. Will be `null` if there are no errors. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `code: "server_error" or "rate_limit_exceeded"` - - `status: "in_progress" or "incomplete" or "completed"` + One of `server_error` or `rate_limit_exceeded`. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"server_error"` - - `"in_progress"` + - `"rate_limit_exceeded"` - - `"incomplete"` + - `message: string` - - `"completed"` + A human-readable description of the error. - - `thread_id: string` - - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `metadata: map[string]` - - `first_id: string` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `has_more: boolean` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `last_id: string` + - `object: "thread.run.step"` - - `object: string` + The object type, which is always `thread.run.step`. -### Example + - `run_id: string` -```cli -openai beta:threads:messages list \ - --api-key 'My API Key' \ - --thread-id thread_id -``` + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. -#### Response + - `status: "in_progress" or "cancelled" or "failed" or 2 more` -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" -} -``` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. -## Create message + - `"in_progress"` -`$ openai beta:threads:messages create` + - `"cancelled"` -**post** `/threads/{thread_id}/messages` + - `"failed"` -Create message + - `"completed"` -### Parameters + - `"expired"` -- `--thread-id: string` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to create a message for. + The details of the run step. -- `--content: string or array of MessageContentPartParam` + - `message_creation_step_details: object { message_creation, type }` - The text contents of the message. + Details of the message creation by the run step. -- `--role: "user" or "assistant"` + - `message_creation: object { message_id }` - The role of the entity that is creating the message. Allowed values include: + - `message_id: string` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + The ID of the message that was created by this run step. -- `--attachment: optional array of object { file_id, tools }` + - `type: "message_creation"` - A list of files attached to the message, and the tools they should be added to. + Always `message_creation`. -- `--metadata: optional map[string]` + - `tool_calls_step_details: object { tool_calls, type }` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + Details of the tool call. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `tool_calls: array of ToolCall` -### Returns + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. -- `message: object { id, assistant_id, attachments, 11 more }` + - `code_interpreter_tool_call: object { id, code_interpreter, type }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + Details of the Code Interpreter tool call the run step was involved in. - `id: string` - The identifier, which can be referenced in API endpoints. + The ID of the tool call. - - `assistant_id: string` + - `code_interpreter: object { input, outputs }` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The Code Interpreter tool call definition. - - `attachments: array of object { file_id, tools }` + - `input: string` - A list of files attached to the message, and the tools they were added to. + The input to the Code Interpreter tool call. - - `file_id: optional string` + - `outputs: array of object { logs, type } or object { image, type }` - The ID of the file to attach to the message. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `logs: object { logs, type }` - The tools to add this file to. + Text output from the Code Interpreter tool call as part of a run step. - - `code_interpreter_tool: object { type }` + - `logs: string` - - `type: "code_interpreter"` + The text output from the Code Interpreter tool call. - The type of tool being defined: `code_interpreter` + - `type: "logs"` - - `AssistantToolsFileSearchTypeOnly: object { type }` + Always `logs`. - - `completed_at: number` + - `image: object { image, type }` - The Unix timestamp (in seconds) for when the message was completed. + - `image: object { file_id }` - - `content: array of unknown` + - `file_id: string` - The content of the message in array of text and/or images. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `created_at: number` + - `type: "image"` - The Unix timestamp (in seconds) for when the message was created. + Always `image`. - - `incomplete_at: number` + - `type: "code_interpreter"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `incomplete_details: object { reason }` + - `file_search_tool_call: object { id, file_search, type }` - On an incomplete message, details about why the message is incomplete. + - `id: string` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The ID of the tool call object. - The reason the message is incomplete. + - `file_search: object { ranking_options, results }` - - `"content_filter"` + For now, this is always going to be an empty object. - - `"max_tokens"` + - `ranking_options: optional object { ranker, score_threshold }` - - `"run_cancelled"` + The ranking options for the file search. - - `"run_expired"` + - `ranker: "auto" or "default_2024_08_21"` - - `"run_failed"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `metadata: map[string]` + - `"auto"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"default_2024_08_21"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `score_threshold: number` - - `object: "thread.message"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The object type, which is always `thread.message`. + - `results: optional array of object { file_id, file_name, score, content }` - - `role: "user" or "assistant"` + The results of the file search. - The entity that produced the message. One of `user` or `assistant`. + - `file_id: string` - - `"user"` + The ID of the file that result was found in. - - `"assistant"` + - `file_name: string` - - `run_id: string` + The name of the file that result was found in. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `score: number` - - `status: "in_progress" or "incomplete" or "completed"` + The score of the result. All values must be a floating point number between 0 and 1. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `content: optional array of object { text, type }` - - `"in_progress"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `"incomplete"` + - `text: optional string` - - `"completed"` + The text content of the file. - - `thread_id: string` + - `type: optional "text"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The type of the content. -### Example + - `"text"` -```cli -openai beta:threads:messages create \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --content string \ - --role user -``` + - `type: "file_search"` -#### Response + The type of tool call. This is always going to be `file_search` for this type of tool call. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `function_tool_call: object { id, function, type }` -## Modify message + - `id: string` -`$ openai beta:threads:messages update` + The ID of the tool call object. -**post** `/threads/{thread_id}/messages/{message_id}` + - `function: object { arguments, name, output }` -Modify message + The definition of the function that was called. -### Parameters + - `arguments: string` + + The arguments passed to the function. + + - `name: string` + + The name of the function. + + - `output: string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `type: "tool_calls"` + + Always `tool_calls`. + + - `thread_id: string` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + + - `type: "message_creation" or "tool_calls"` + + The type of run step, which can be either `message_creation` or `tool_calls`. + + - `"message_creation"` + + - `"tool_calls"` + + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + + - `completion_tokens: number` + + Number of completion tokens used over the course of the run step. + + - `prompt_tokens: number` + + Number of prompt tokens used over the course of the run step. + + - `total_tokens: number` + + Total number of tokens used (prompt + completion). + +### Run Step Delta + +- `run_step_delta: object { step_details }` + + The delta containing the fields that have changed on the run step. + + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + + The details of the run step. + + - `run_step_delta_message_delta: object { type, message_creation }` + + Details of the message creation by the run step. + + - `type: "message_creation"` + + Always `message_creation`. + + - `message_creation: optional object { message_id }` + + - `message_id: optional string` + + The ID of the message that was created by this run step. + + - `tool_call_delta_object: object { type, tool_calls }` + + Details of the tool call. + + - `type: "tool_calls"` + + Always `tool_calls`. + + - `tool_calls: optional array of ToolCallDelta` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `id: optional string` + + The ID of the tool call. + + - `code_interpreter: optional object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: optional string` + + The input to the Code Interpreter tool call. + + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `code_interpreter_logs: object { index, type, logs }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: number` + + The index of the output in the outputs array. + + - `type: "logs"` + + Always `logs`. + + - `logs: optional string` + + The text output from the Code Interpreter tool call. + + - `code_interpreter_output_image: object { index, type, image }` + + - `index: number` + + The index of the output in the outputs array. + + - `type: "image"` + + Always `image`. + + - `image: optional object { file_id }` + + - `file_id: optional string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `file_search_tool_call_delta: object { file_search, index, type, id }` + + - `file_search: unknown` + + For now, this is always going to be an empty object. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function_tool_call_delta: object { index, type, id, function }` + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function: optional object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: optional string` + + The arguments passed to the function. + + - `name: optional string` + + The name of the function. + + - `output: optional string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Run Step Delta Event + +- `run_step_delta_event: object { id, delta, object }` + + Represents a run step delta i.e. any changed fields on a run step during streaming. + + - `id: string` + + The identifier of the run step, which can be referenced in API endpoints. + + - `delta: object { step_details }` + + The delta containing the fields that have changed on the run step. + + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + + The details of the run step. + + - `run_step_delta_message_delta: object { type, message_creation }` + + Details of the message creation by the run step. + + - `type: "message_creation"` + + Always `message_creation`. + + - `message_creation: optional object { message_id }` + + - `message_id: optional string` + + The ID of the message that was created by this run step. + + - `tool_call_delta_object: object { type, tool_calls }` + + Details of the tool call. + + - `type: "tool_calls"` + + Always `tool_calls`. + + - `tool_calls: optional array of ToolCallDelta` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `id: optional string` + + The ID of the tool call. + + - `code_interpreter: optional object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: optional string` + + The input to the Code Interpreter tool call. + + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `code_interpreter_logs: object { index, type, logs }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: number` + + The index of the output in the outputs array. + + - `type: "logs"` + + Always `logs`. + + - `logs: optional string` + + The text output from the Code Interpreter tool call. + + - `code_interpreter_output_image: object { index, type, image }` + + - `index: number` + + The index of the output in the outputs array. + + - `type: "image"` + + Always `image`. + + - `image: optional object { file_id }` + + - `file_id: optional string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `file_search_tool_call_delta: object { file_search, index, type, id }` + + - `file_search: unknown` + + For now, this is always going to be an empty object. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function_tool_call_delta: object { index, type, id, function }` + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function: optional object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: optional string` + + The arguments passed to the function. + + - `name: optional string` + + The name of the function. + + - `output: optional string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `object: "thread.run.step.delta"` + + The object type, which is always `thread.run.step.delta`. + +### Run Step Delta Message Delta + +- `run_step_delta_message_delta: object { type, message_creation }` + + Details of the message creation by the run step. + + - `type: "message_creation"` + + Always `message_creation`. + + - `message_creation: optional object { message_id }` + + - `message_id: optional string` + + The ID of the message that was created by this run step. + +### Run Step Include + +- `run_step_include: "step_details.tool_calls[*].file_search.results[*].content"` + + - `"step_details.tool_calls[*].file_search.results[*].content"` + +### Tool Call + +- `tool_call: CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + + Details of the Code Interpreter tool call the run step was involved in. + + - `code_interpreter_tool_call: object { id, code_interpreter, type }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `id: string` + + The ID of the tool call. + + - `code_interpreter: object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: string` + + The input to the Code Interpreter tool call. + + - `outputs: array of object { logs, type } or object { image, type }` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `logs: object { logs, type }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `logs: string` + + The text output from the Code Interpreter tool call. + + - `type: "logs"` + + Always `logs`. + + - `image: object { image, type }` + + - `image: object { file_id }` + + - `file_id: string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `type: "image"` + + Always `image`. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `file_search_tool_call: object { id, file_search, type }` + + - `id: string` + + The ID of the tool call object. + + - `file_search: object { ranking_options, results }` + + For now, this is always going to be an empty object. + + - `ranking_options: optional object { ranker, score_threshold }` + + The ranking options for the file search. + + - `ranker: "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: optional array of object { file_id, file_name, score, content }` + + The results of the file search. + + - `file_id: string` + + The ID of the file that result was found in. + + - `file_name: string` + + The name of the file that result was found in. + + - `score: number` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: optional array of object { text, type }` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: optional string` + + The text content of the file. + + - `type: optional "text"` + + The type of the content. + + - `"text"` + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `function_tool_call: object { id, function, type }` + + - `id: string` + + The ID of the tool call object. + + - `function: object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: string` + + The arguments passed to the function. + + - `name: string` + + The name of the function. + + - `output: string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + +### Tool Call Delta + +- `tool_call_delta: CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + + Details of the Code Interpreter tool call the run step was involved in. + + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `id: optional string` + + The ID of the tool call. + + - `code_interpreter: optional object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: optional string` + + The input to the Code Interpreter tool call. + + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `code_interpreter_logs: object { index, type, logs }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: number` + + The index of the output in the outputs array. + + - `type: "logs"` + + Always `logs`. + + - `logs: optional string` + + The text output from the Code Interpreter tool call. + + - `code_interpreter_output_image: object { index, type, image }` + + - `index: number` + + The index of the output in the outputs array. + + - `type: "image"` + + Always `image`. + + - `image: optional object { file_id }` + + - `file_id: optional string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `file_search_tool_call_delta: object { file_search, index, type, id }` + + - `file_search: unknown` + + For now, this is always going to be an empty object. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function_tool_call_delta: object { index, type, id, function }` + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function: optional object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: optional string` + + The arguments passed to the function. + + - `name: optional string` + + The name of the function. + + - `output: optional string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Tool Call Delta Object + +- `tool_call_delta_object: object { type, tool_calls }` + + Details of the tool call. + + - `type: "tool_calls"` + + Always `tool_calls`. + + - `tool_calls: optional array of ToolCallDelta` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `id: optional string` + + The ID of the tool call. + + - `code_interpreter: optional object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: optional string` + + The input to the Code Interpreter tool call. + + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `code_interpreter_logs: object { index, type, logs }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: number` + + The index of the output in the outputs array. + + - `type: "logs"` + + Always `logs`. + + - `logs: optional string` + + The text output from the Code Interpreter tool call. + + - `code_interpreter_output_image: object { index, type, image }` + + - `index: number` + + The index of the output in the outputs array. + + - `type: "image"` + + Always `image`. + + - `image: optional object { file_id }` + + - `file_id: optional string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `file_search_tool_call_delta: object { file_search, index, type, id }` + + - `file_search: unknown` + + For now, this is always going to be an empty object. + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function_tool_call_delta: object { index, type, id, function }` + + - `index: number` + + The index of the tool call in the tool calls array. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `id: optional string` + + The ID of the tool call object. + + - `function: optional object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: optional string` + + The arguments passed to the function. + + - `name: optional string` + + The name of the function. + + - `output: optional string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Tool Calls Step Details + +- `tool_calls_step_details: object { tool_calls, type }` + + Details of the tool call. + + - `tool_calls: array of ToolCall` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `code_interpreter_tool_call: object { id, code_interpreter, type }` + + Details of the Code Interpreter tool call the run step was involved in. + + - `id: string` + + The ID of the tool call. + + - `code_interpreter: object { input, outputs }` + + The Code Interpreter tool call definition. + + - `input: string` + + The input to the Code Interpreter tool call. + + - `outputs: array of object { logs, type } or object { image, type }` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `logs: object { logs, type }` + + Text output from the Code Interpreter tool call as part of a run step. + + - `logs: string` + + The text output from the Code Interpreter tool call. + + - `type: "logs"` + + Always `logs`. + + - `image: object { image, type }` + + - `image: object { file_id }` + + - `file_id: string` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `type: "image"` + + Always `image`. + + - `type: "code_interpreter"` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `file_search_tool_call: object { id, file_search, type }` + + - `id: string` + + The ID of the tool call object. + + - `file_search: object { ranking_options, results }` + + For now, this is always going to be an empty object. + + - `ranking_options: optional object { ranker, score_threshold }` + + The ranking options for the file search. + + - `ranker: "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: optional array of object { file_id, file_name, score, content }` + + The results of the file search. + + - `file_id: string` + + The ID of the file that result was found in. + + - `file_name: string` + + The name of the file that result was found in. + + - `score: number` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: optional array of object { text, type }` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: optional string` + + The text content of the file. + + - `type: optional "text"` + + The type of the content. + + - `"text"` + + - `type: "file_search"` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `function_tool_call: object { id, function, type }` + + - `id: string` + + The ID of the tool call object. + + - `function: object { arguments, name, output }` + + The definition of the function that was called. + + - `arguments: string` + + The arguments passed to the function. + + - `name: string` + + The name of the function. + + - `output: string` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: "function"` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `type: "tool_calls"` + + Always `tool_calls`. + +# Messages + +## List messages + +`$ openai beta:threads:messages list` + +**get** `/threads/{thread_id}/messages` + +Returns a list of messages for a given thread. + +### Parameters + +- `--thread-id: string` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) the messages belong to. + +- `--after: optional string` + + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + +- `--before: optional string` + + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + +- `--limit: optional number` + + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + +- `--order: optional "asc" or "desc"` + + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + +- `--run-id: optional string` + + Filter messages by the run ID that generated them. + +### Returns + +- `ListMessagesResponse: object { data, first_id, has_more, 2 more }` + + - `data: array of Message` + + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: string` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `AssistantToolsFileSearchTypeOnly: object { type }` + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the message was completed. + + - `content: array of MessageContent` + + The content of the message in array of text and/or images. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block: object { text, type }` + + The text content that is part of a message. + + - `text: object { annotations, value }` + + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + + - `value: string` + + The data that makes up the text. + + - `type: "text"` + + Always `text`. + + - `refusal_content_block: object { refusal, type }` + + The refusal content generated by the assistant. + + - `refusal: string` + + - `type: "refusal"` + + Always `refusal`. + + - `created_at: number` + + The Unix timestamp (in seconds) for when the message was created. + + - `incomplete_at: number` + + The Unix timestamp (in seconds) for when the message was marked as incomplete. + + - `incomplete_details: object { reason }` + + On an incomplete message, details about why the message is incomplete. + + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` + + - `metadata: map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + + - `object: "thread.message"` + + The object type, which is always `thread.message`. + + - `role: "user" or "assistant"` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: string` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + + - `first_id: string` + + - `has_more: boolean` + + - `last_id: string` + + - `object: string` + +### Example + +```cli +openai beta:threads:messages list \ + --api-key 'My API Key' \ + --thread-id thread_id +``` + +#### Response + +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` + +## Create message + +`$ openai beta:threads:messages create` + +**post** `/threads/{thread_id}/messages` + +Create a message. + +### Parameters + +- `--thread-id: string` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to create a message for. + +- `--content: string or array of MessageContentPartParam` + + The text contents of the message. + +- `--role: "user" or "assistant"` + + The role of the entity that is creating the message. Allowed values include: + + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + +- `--attachment: optional array of object { file_id, tools }` + + A list of files attached to the message, and the tools they should be added to. + +- `--metadata: optional map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +### Returns + +- `message: object { id, assistant_id, attachments, 11 more }` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: string` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `AssistantToolsFileSearchTypeOnly: object { type }` + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the message was completed. + + - `content: array of MessageContent` + + The content of the message in array of text and/or images. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block: object { text, type }` + + The text content that is part of a message. + + - `text: object { annotations, value }` + + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + + - `value: string` + + The data that makes up the text. + + - `type: "text"` + + Always `text`. + + - `refusal_content_block: object { refusal, type }` + + The refusal content generated by the assistant. + + - `refusal: string` + + - `type: "refusal"` + + Always `refusal`. + + - `created_at: number` + + The Unix timestamp (in seconds) for when the message was created. + + - `incomplete_at: number` + + The Unix timestamp (in seconds) for when the message was marked as incomplete. + + - `incomplete_details: object { reason }` + + On an incomplete message, details about why the message is incomplete. + + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` + + - `metadata: map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + + - `object: "thread.message"` + + The object type, which is always `thread.message`. + + - `role: "user" or "assistant"` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: string` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```cli +openai beta:threads:messages create \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --content string \ + --role user +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` + +## Modify message + +`$ openai beta:threads:messages update` + +**post** `/threads/{thread_id}/messages/{message_id}` + +Modifies a message. + +### Parameters + +- `--thread-id: string` + + The ID of the thread to which this message belongs. + +- `--message-id: string` + + The ID of the message to modify. + +- `--metadata: optional map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + +### Returns + +- `message: object { id, assistant_id, attachments, 11 more }` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: string` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `AssistantToolsFileSearchTypeOnly: object { type }` + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the message was completed. + + - `content: array of MessageContent` + + The content of the message in array of text and/or images. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block: object { text, type }` + + The text content that is part of a message. + + - `text: object { annotations, value }` + + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + + - `value: string` + + The data that makes up the text. + + - `type: "text"` + + Always `text`. + + - `refusal_content_block: object { refusal, type }` + + The refusal content generated by the assistant. + + - `refusal: string` + + - `type: "refusal"` + + Always `refusal`. + + - `created_at: number` + + The Unix timestamp (in seconds) for when the message was created. + + - `incomplete_at: number` + + The Unix timestamp (in seconds) for when the message was marked as incomplete. + + - `incomplete_details: object { reason }` + + On an incomplete message, details about why the message is incomplete. + + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` + + - `metadata: map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + + - `object: "thread.message"` + + The object type, which is always `thread.message`. + + - `role: "user" or "assistant"` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: string` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```cli +openai beta:threads:messages update \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` + +## Retrieve message + +`$ openai beta:threads:messages retrieve` + +**get** `/threads/{thread_id}/messages/{message_id}` + +Retrieve a message. + +### Parameters + +- `--thread-id: string` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this message belongs. + +- `--message-id: string` + + The ID of the message to retrieve. + +### Returns + +- `message: object { id, assistant_id, attachments, 11 more }` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: string` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: string` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `code_interpreter_tool: object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `AssistantToolsFileSearchTypeOnly: object { type }` + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the message was completed. + + - `content: array of MessageContent` + + The content of the message in array of text and/or images. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block: object { text, type }` + + The text content that is part of a message. + + - `text: object { annotations, value }` + + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + + - `value: string` + + The data that makes up the text. + + - `type: "text"` + + Always `text`. + + - `refusal_content_block: object { refusal, type }` + + The refusal content generated by the assistant. + + - `refusal: string` + + - `type: "refusal"` + + Always `refusal`. + + - `created_at: number` + + The Unix timestamp (in seconds) for when the message was created. + + - `incomplete_at: number` + + The Unix timestamp (in seconds) for when the message was marked as incomplete. + + - `incomplete_details: object { reason }` + + On an incomplete message, details about why the message is incomplete. + + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` + + - `metadata: map[string]` + + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + + - `object: "thread.message"` + + The object type, which is always `thread.message`. + + - `role: "user" or "assistant"` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: string` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```cli +openai beta:threads:messages retrieve \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` + +## Delete message + +`$ openai beta:threads:messages delete` + +**delete** `/threads/{thread_id}/messages/{message_id}` + +Deletes a message. + +### Parameters + +- `--thread-id: string` + + The ID of the thread to which this message belongs. + +- `--message-id: string` + + The ID of the message to delete. + +### Returns + +- `message_deleted: object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "thread.message.deleted"` + +### Example + +```cli +openai beta:threads:messages delete \ + --api-key 'My API Key' \ + --thread-id thread_id \ + --message-id message_id +``` + +#### Response + +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` + +## Domain Types + +### Annotation + +- `annotation: FileCitationAnnotation or FilePathAnnotation` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + +### Annotation Delta + +- `annotation_delta: FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_citation"` + + Always `file_citation`. + + - `end_index: optional number` + + - `file_citation: optional object { file_id, quote }` + + - `file_id: optional string` + + The ID of the specific File the citation is from. + + - `quote: optional string` + + The specific quote in the file. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_path"` + + Always `file_path`. + + - `end_index: optional number` + + - `file_path: optional object { file_id }` + + - `file_id: optional string` + + The ID of the file that was generated. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + +### File Citation Annotation + +- `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + +### File Citation Delta Annotation + +- `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_citation"` + + Always `file_citation`. -- `--thread-id: string` + - `end_index: optional number` - The ID of the thread to which this message belongs. + - `file_citation: optional object { file_id, quote }` -- `--message-id: string` + - `file_id: optional string` - The ID of the message to modify. + The ID of the specific File the citation is from. -- `--metadata: optional map[string]` + - `quote: optional string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The specific quote in the file. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + +### File Path Annotation + +- `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + +### File Path Delta Annotation + +- `file_path_delta_annotation: object { index, type, end_index, 3 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_path"` + + Always `file_path`. + + - `end_index: optional number` + + - `file_path: optional object { file_id }` + + - `file_id: optional string` + + The ID of the file that was generated. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + +### Image File + +- `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + +### Image File Content Block + +- `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + +### Image File Delta + +- `image_file_delta: object { detail, file_id }` + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_id: optional string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + +### Image File Delta Block + +- `image_file_delta_block: object { index, type, image_file }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `index: number` + + The index of the content part in the message. + + - `type: "image_file"` + + Always `image_file`. + + - `image_file: optional object { detail, file_id }` + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `file_id: optional string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + +### Image URL + +- `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + +### Image URL Content Block + +- `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + +### Image URL Delta + +- `image_url_delta: object { detail, url }` + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `url: optional string` + + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + +### Image URL Delta Block + +- `image_url_delta_block: object { index, type, image_url }` + + References an image URL in the content of a message. + + - `index: number` + + The index of the content part in the message. + + - `type: "image_url"` + + Always `image_url`. + + - `image_url: optional object { detail, url }` + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `url: optional string` -### Returns + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + +### Message - `message: object { id, assistant_id, attachments, 11 more }` @@ -5196,179 +8359,127 @@ Modify message The Unix timestamp (in seconds) for when the message was completed. - - `content: array of unknown` + - `content: array of MessageContent` The content of the message in array of text and/or images. - - `created_at: number` - - The Unix timestamp (in seconds) for when the message was created. - - - `incomplete_at: number` - - The Unix timestamp (in seconds) for when the message was marked as incomplete. - - - `incomplete_details: object { reason }` - - On an incomplete message, details about why the message is incomplete. - - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `image_file_content_block: object { image_file, type }` - The reason the message is incomplete. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"content_filter"` + - `image_file: object { file_id, detail }` - - `"max_tokens"` + - `file_id: string` - - `"run_cancelled"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"run_expired"` + - `detail: optional "auto" or "low" or "high"` - - `"run_failed"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `metadata: map[string]` + - `"auto"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"low"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"high"` - - `object: "thread.message"` + - `type: "image_file"` - The object type, which is always `thread.message`. + Always `image_file`. - - `role: "user" or "assistant"` + - `image_url_content_block: object { image_url, type }` - The entity that produced the message. One of `user` or `assistant`. + References an image URL in the content of a message. - - `"user"` + - `image_url: object { url, detail }` - - `"assistant"` + - `url: string` - - `run_id: string` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `detail: optional "auto" or "low" or "high"` - - `status: "in_progress" or "incomplete" or "completed"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"incomplete"` + - `"high"` - - `"completed"` + - `type: "image_url"` - - `thread_id: string` + The type of the content part. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `text_content_block: object { text, type }` -### Example + The text content that is part of a message. -```cli -openai beta:threads:messages update \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + - `text: object { annotations, value }` -#### Response + - `annotations: array of Annotation` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` -## Retrieve message + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. -`$ openai beta:threads:messages retrieve` + - `end_index: number` -**get** `/threads/{thread_id}/messages/{message_id}` + - `file_citation: object { file_id }` -Retrieve message + - `file_id: string` -### Parameters + The ID of the specific File the citation is from. -- `--thread-id: string` + - `start_index: number` - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) to which this message belongs. + - `text: string` -- `--message-id: string` + The text in the message content that needs to be replaced. - The ID of the message to retrieve. + - `type: "file_citation"` -### Returns + Always `file_citation`. -- `message: object { id, assistant_id, attachments, 11 more }` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `id: string` + - `end_index: number` - The identifier, which can be referenced in API endpoints. + - `file_path: object { file_id }` - - `assistant_id: string` + - `file_id: string` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + The ID of the file that was generated. - - `attachments: array of object { file_id, tools }` + - `start_index: number` - A list of files attached to the message, and the tools they were added to. + - `text: string` - - `file_id: optional string` + The text in the message content that needs to be replaced. - The ID of the file to attach to the message. + - `type: "file_path"` - - `tools: optional array of CodeInterpreterTool or object { type }` + Always `file_path`. - The tools to add this file to. + - `value: string` - - `code_interpreter_tool: object { type }` + The data that makes up the text. - - `type: "code_interpreter"` + - `type: "text"` - The type of tool being defined: `code_interpreter` + Always `text`. - - `AssistantToolsFileSearchTypeOnly: object { type }` + - `refusal_content_block: object { refusal, type }` - - `completed_at: number` + The refusal content generated by the assistant. - The Unix timestamp (in seconds) for when the message was completed. + - `refusal: string` - - `content: array of unknown` + - `type: "refusal"` - The content of the message in array of text and/or images. + Always `refusal`. - `created_at: number` @@ -5421,149 +8532,195 @@ Retrieve message The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `status: "in_progress" or "incomplete" or "completed"` + - `status: "in_progress" or "incomplete" or "completed"` + + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: string` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Message Content + +- `message_content: ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` + + - `file_id: string` + + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block: object { text, type }` + + The text content that is part of a message. + + - `text: object { annotations, value }` + + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + Always `file_citation`. - - `"in_progress"` + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` - - `"incomplete"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"completed"` + - `end_index: number` - - `thread_id: string` + - `file_path: object { file_id }` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `file_id: string` -### Example + The ID of the file that was generated. -```cli -openai beta:threads:messages retrieve \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + - `start_index: number` -#### Response + - `text: string` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + The text in the message content that needs to be replaced. -## Delete message + - `type: "file_path"` -`$ openai beta:threads:messages delete` + Always `file_path`. -**delete** `/threads/{thread_id}/messages/{message_id}` + - `value: string` -Delete message + The data that makes up the text. -### Parameters + - `type: "text"` -- `--thread-id: string` + Always `text`. - The ID of the thread to which this message belongs. + - `refusal_content_block: object { refusal, type }` -- `--message-id: string` + The refusal content generated by the assistant. - The ID of the message to delete. + - `refusal: string` -### Returns + - `type: "refusal"` -- `message_deleted: object { id, deleted, object }` + Always `refusal`. - - `id: string` +### Message Content Delta - - `deleted: boolean` +- `message_content_delta: ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `object: "thread.message.deleted"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -### Example + - `image_file_delta_block: object { index, type, image_file }` -```cli -openai beta:threads:messages delete \ - --api-key 'My API Key' \ - --thread-id thread_id \ - --message-id message_id -``` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -#### Response + - `index: number` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + The index of the content part in the message. -## Domain Types + - `type: "image_file"` -### Annotation + Always `image_file`. -- `annotation: unknown` + - `image_file: optional object { detail, file_id }` -### Annotation Delta + - `detail: optional "auto" or "low" or "high"` -- `annotation_delta: unknown` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. -### File Citation Annotation + - `"auto"` -- `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + - `"low"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `"high"` - - `end_index: number` + - `file_id: optional string` - - `file_citation: object { file_id }` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `file_id: string` + - `text_delta_block: object { index, type, text }` - The ID of the specific File the citation is from. + The text content that is part of a message. - - `start_index: number` + - `index: number` - - `text: string` + The index of the content part in the message. - The text in the message content that needs to be replaced. + - `type: "text"` - - `type: "file_citation"` + Always `text`. - Always `file_citation`. + - `text: optional object { annotations, value }` -### File Citation Delta Annotation + - `annotations: optional array of AnnotationDelta` -- `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. @@ -5593,61 +8750,89 @@ openai beta:threads:messages delete \ The text in the message content that needs to be replaced. -### File Path Annotation - -- `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `end_index: number` + - `index: number` - - `file_path: object { file_id }` + The index of the annotation in the text content part. - - `file_id: string` + - `type: "file_path"` + + Always `file_path`. + + - `end_index: optional number` + + - `file_path: optional object { file_id }` + + - `file_id: optional string` The ID of the file that was generated. - - `start_index: number` + - `start_index: optional number` - - `text: string` + - `text: optional string` The text in the message content that needs to be replaced. - - `type: "file_path"` + - `value: optional string` - Always `file_path`. + The data that makes up the text. -### File Path Delta Annotation + - `refusal_delta_block: object { index, type, refusal }` -- `file_path_delta_annotation: object { index, type, end_index, 3 more }` + The refusal content that is part of a message. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `index: number` + + The index of the refusal part in the message. + + - `type: "refusal"` + + Always `refusal`. + + - `refusal: optional string` + + - `image_url_delta_block: object { index, type, image_url }` + + References an image URL in the content of a message. - `index: number` - The index of the annotation in the text content part. + The index of the content part in the message. - - `type: "file_path"` + - `type: "image_url"` - Always `file_path`. + Always `image_url`. - - `end_index: optional number` + - `image_url: optional object { detail, url }` - - `file_path: optional object { file_id }` + - `detail: optional "auto" or "low" or "high"` - - `file_id: optional string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The ID of the file that was generated. + - `"auto"` - - `start_index: optional number` + - `"low"` - - `text: optional string` + - `"high"` - The text in the message content that needs to be replaced. + - `url: optional string` -### Image File + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -- `image_file: object { file_id, detail }` +### Message Content Part Param + +- `message_content_part_param: ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file_content_block: object { image_file, type }` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: object { file_id, detail }` - `file_id: string` @@ -5663,35 +8848,79 @@ openai beta:threads:messages delete \ - `"high"` -### Image File Content Block + - `type: "image_file"` + + Always `image_file`. + + - `image_url_content_block: object { image_url, type }` + + References an image URL in the content of a message. + + - `image_url: object { url, detail }` + + - `url: string` + + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `detail: optional "auto" or "low" or "high"` + + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: "image_url"` + + The type of the content part. + + - `text_content_block_param: object { text, type }` + + The text content that is part of a message. + + - `text: string` + + Text content to be sent to the model + + - `type: "text"` + + Always `text`. + +### Message Deleted + +- `message_deleted: object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` -- `image_file_content_block: object { image_file, type }` + - `object: "thread.message.deleted"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. +### Message Delta - - `image_file: object { file_id, detail }` +- `message_delta: object { content, role }` - - `file_id: string` + The delta containing the fields that have changed on the Message. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `content: optional array of MessageContentDelta` - - `detail: optional "auto" or "low" or "high"` + The content of the message in array of text and/or images. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `image_file_delta_block: object { index, type, image_file }` - - `"auto"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"low"` + - `index: number` - - `"high"` + The index of the content part in the message. - `type: "image_file"` Always `image_file`. -### Image File Delta - -- `image_file_delta: object { detail, file_id }` + - `image_file: optional object { detail, file_id }` - `detail: optional "auto" or "low" or "high"` @@ -5707,101 +8936,97 @@ openai beta:threads:messages delete \ The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -### Image File Delta Block - -- `image_file_delta_block: object { index, type, image_file }` + - `text_delta_block: object { index, type, text }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The text content that is part of a message. - `index: number` The index of the content part in the message. - - `type: "image_file"` - - Always `image_file`. + - `type: "text"` - - `image_file: optional object { detail, file_id }` + Always `text`. - - `detail: optional "auto" or "low" or "high"` + - `text: optional object { annotations, value }` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `annotations: optional array of AnnotationDelta` - - `"auto"` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `"low"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"high"` + - `index: number` - - `file_id: optional string` + The index of the annotation in the text content part. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `type: "file_citation"` -### Image URL + Always `file_citation`. -- `image_url: object { url, detail }` + - `end_index: optional number` - - `url: string` + - `file_citation: optional object { file_id, quote }` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `file_id: optional string` - - `detail: optional "auto" or "low" or "high"` + The ID of the specific File the citation is from. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `quote: optional string` - - `"auto"` + The specific quote in the file. - - `"low"` + - `start_index: optional number` - - `"high"` + - `text: optional string` -### Image URL Content Block + The text in the message content that needs to be replaced. -- `image_url_content_block: object { image_url, type }` + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - References an image URL in the content of a message. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `image_url: object { url, detail }` + - `index: number` - - `url: string` + The index of the annotation in the text content part. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "file_path"` - - `detail: optional "auto" or "low" or "high"` + Always `file_path`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `end_index: optional number` - - `"auto"` + - `file_path: optional object { file_id }` - - `"low"` + - `file_id: optional string` - - `"high"` + The ID of the file that was generated. - - `type: "image_url"` + - `start_index: optional number` - The type of the content part. + - `text: optional string` -### Image URL Delta + The text in the message content that needs to be replaced. -- `image_url_delta: object { detail, url }` + - `value: optional string` - - `detail: optional "auto" or "low" or "high"` + The data that makes up the text. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `refusal_delta_block: object { index, type, refusal }` - - `"auto"` + The refusal content that is part of a message. - - `"low"` + - `index: number` - - `"high"` + The index of the refusal part in the message. - - `url: optional string` + - `type: "refusal"` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Always `refusal`. -### Image URL Delta Block + - `refusal: optional string` -- `image_url_delta_block: object { index, type, image_url }` + - `image_url_delta_block: object { index, type, image_url }` References an image URL in the content of a message. @@ -5829,232 +9054,177 @@ openai beta:threads:messages delete \ The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -### Message - -- `message: object { id, assistant_id, attachments, 11 more }` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `id: string` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: string` - - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - - `attachments: array of object { file_id, tools }` - - A list of files attached to the message, and the tools they were added to. + - `role: optional "user" or "assistant"` - - `file_id: optional string` + The entity that produced the message. One of `user` or `assistant`. - The ID of the file to attach to the message. + - `"user"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `"assistant"` - The tools to add this file to. +### Message Delta Event - - `code_interpreter_tool: object { type }` +- `message_delta_event: object { id, delta, object }` - - `type: "code_interpreter"` + Represents a message delta i.e. any changed fields on a message during streaming. - The type of tool being defined: `code_interpreter` + - `id: string` - - `AssistantToolsFileSearchTypeOnly: object { type }` + The identifier of the message, which can be referenced in API endpoints. - - `completed_at: number` + - `delta: object { content, role }` - The Unix timestamp (in seconds) for when the message was completed. + The delta containing the fields that have changed on the Message. - - `content: array of unknown` + - `content: optional array of MessageContentDelta` The content of the message in array of text and/or images. - - `created_at: number` - - The Unix timestamp (in seconds) for when the message was created. - - - `incomplete_at: number` - - The Unix timestamp (in seconds) for when the message was marked as incomplete. - - - `incomplete_details: object { reason }` - - On an incomplete message, details about why the message is incomplete. - - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - The reason the message is incomplete. - - - `"content_filter"` - - - `"max_tokens"` - - - `"run_cancelled"` - - - `"run_expired"` - - - `"run_failed"` - - - `metadata: map[string]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: "thread.message"` - - The object type, which is always `thread.message`. + - `image_file_delta_block: object { index, type, image_file }` - - `role: "user" or "assistant"` - - The entity that produced the message. One of `user` or `assistant`. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `"user"` + - `index: number` - - `"assistant"` + The index of the content part in the message. - - `run_id: string` + - `type: "image_file"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + Always `image_file`. - - `status: "in_progress" or "incomplete" or "completed"` + - `image_file: optional object { detail, file_id }` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `detail: optional "auto" or "low" or "high"` - - `"in_progress"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"incomplete"` + - `"auto"` - - `"completed"` + - `"low"` - - `thread_id: string` + - `"high"` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `file_id: optional string` -### Message Content + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -- `message_content: unknown` + - `text_delta_block: object { index, type, text }` -### Message Content Delta + The text content that is part of a message. -- `message_content_delta: unknown` + - `index: number` -### Message Content Part Param + The index of the content part in the message. -- `message_content_part_param: ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + - `type: "text"` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + Always `text`. - - `image_file_content_block: object { image_file, type }` + - `text: optional object { annotations, value }` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `annotations: optional array of AnnotationDelta` - - `image_file: object { file_id, detail }` + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` - - `file_id: string` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `index: number` - - `detail: optional "auto" or "low" or "high"` + The index of the annotation in the text content part. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `type: "file_citation"` - - `"auto"` + Always `file_citation`. - - `"low"` + - `end_index: optional number` - - `"high"` + - `file_citation: optional object { file_id, quote }` - - `type: "image_file"` + - `file_id: optional string` - Always `image_file`. + The ID of the specific File the citation is from. - - `image_url_content_block: object { image_url, type }` + - `quote: optional string` - References an image URL in the content of a message. + The specific quote in the file. - - `image_url: object { url, detail }` + - `start_index: optional number` - - `url: string` + - `text: optional string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The text in the message content that needs to be replaced. - - `detail: optional "auto" or "low" or "high"` + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"auto"` + - `index: number` - - `"low"` + The index of the annotation in the text content part. - - `"high"` + - `type: "file_path"` - - `type: "image_url"` + Always `file_path`. - The type of the content part. + - `end_index: optional number` - - `text_content_block_param: object { text, type }` + - `file_path: optional object { file_id }` - The text content that is part of a message. + - `file_id: optional string` - - `text: string` + The ID of the file that was generated. - Text content to be sent to the model + - `start_index: optional number` - - `type: "text"` + - `text: optional string` - Always `text`. + The text in the message content that needs to be replaced. -### Message Deleted + - `value: optional string` -- `message_deleted: object { id, deleted, object }` + The data that makes up the text. - - `id: string` + - `refusal_delta_block: object { index, type, refusal }` - - `deleted: boolean` + The refusal content that is part of a message. - - `object: "thread.message.deleted"` + - `index: number` -### Message Delta + The index of the refusal part in the message. -- `message_delta: object { content, role }` + - `type: "refusal"` - The delta containing the fields that have changed on the Message. + Always `refusal`. - - `content: optional array of unknown` + - `refusal: optional string` - The content of the message in array of text and/or images. + - `image_url_delta_block: object { index, type, image_url }` - - `role: optional "user" or "assistant"` + References an image URL in the content of a message. - The entity that produced the message. One of `user` or `assistant`. + - `index: number` - - `"user"` + The index of the content part in the message. - - `"assistant"` + - `type: "image_url"` -### Message Delta Event + Always `image_url`. -- `message_delta_event: object { id, delta, object }` + - `image_url: optional object { detail, url }` - Represents a message delta i.e. any changed fields on a message during streaming. + - `detail: optional "auto" or "low" or "high"` - - `id: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The identifier of the message, which can be referenced in API endpoints. + - `"auto"` - - `delta: object { content, role }` + - `"low"` - The delta containing the fields that have changed on the Message. + - `"high"` - - `content: optional array of unknown` + - `url: optional string` - The content of the message in array of text and/or images. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - `role: optional "user" or "assistant"` @@ -6100,7 +9270,51 @@ openai beta:threads:messages delete \ - `text: object { annotations, value }` - - `annotations: array of unknown` + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. - `value: string` @@ -6114,7 +9328,51 @@ openai beta:threads:messages delete \ - `text: object { annotations, value }` - - `annotations: array of unknown` + - `annotations: array of Annotation` + + - `file_citation_annotation: object { end_index, file_citation, start_index, 2 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `end_index: number` + + - `file_citation: object { file_id }` + + - `file_id: string` + + The ID of the specific File the citation is from. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_citation"` + + Always `file_citation`. + + - `file_path_annotation: object { end_index, file_path, start_index, 2 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `end_index: number` + + - `file_path: object { file_id }` + + - `file_id: string` + + The ID of the file that was generated. + + - `start_index: number` + + - `text: string` + + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. - `value: string` @@ -6142,7 +9400,63 @@ openai beta:threads:messages delete \ - `text_delta: object { annotations, value }` - - `annotations: optional array of unknown` + - `annotations: optional array of AnnotationDelta` + + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_citation"` + + Always `file_citation`. + + - `end_index: optional number` + + - `file_citation: optional object { file_id, quote }` + + - `file_id: optional string` + + The ID of the specific File the citation is from. + + - `quote: optional string` + + The specific quote in the file. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_path"` + + Always `file_path`. + + - `end_index: optional number` + + - `file_path: optional object { file_id }` + + - `file_id: optional string` + + The ID of the file that was generated. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. - `value: optional string` @@ -6164,7 +9478,63 @@ openai beta:threads:messages delete \ - `text: optional object { annotations, value }` - - `annotations: optional array of unknown` + - `annotations: optional array of AnnotationDelta` + + - `file_citation_delta_annotation: object { index, type, end_index, 3 more }` + + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_citation"` + + Always `file_citation`. + + - `end_index: optional number` + + - `file_citation: optional object { file_id, quote }` + + - `file_id: optional string` + + The ID of the specific File the citation is from. + + - `quote: optional string` + + The specific quote in the file. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. + + - `file_path_delta_annotation: object { index, type, end_index, 3 more }` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: number` + + The index of the annotation in the text content part. + + - `type: "file_path"` + + Always `file_path`. + + - `end_index: optional number` + + - `file_path: optional object { file_id }` + + - `file_id: optional string` + + The ID of the file that was generated. + + - `start_index: optional number` + + - `text: optional string` + + The text in the message content that needs to be replaced. - `value: optional string`