--- title: "Create an assistant with a model and instructions." method: POST path: "/assistants" tags: ["Assistants"] deprecated: true --- # Create an assistant with a model and instructions. `POST /assistants` > **Deprecated.** ## Request body - CreateAssistantRequest - `model` union, required — ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - string - 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5-2025-08-07' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'o3-mini' | 'o3-mini-2025-01-31' | 'o1' | 'o1-2024-12-17' | 'gpt-4o' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4o-mini' | 'gpt-4o-mini-2024-07-18' | 'gpt-4.5-preview' | 'gpt-4.5-preview-2025-02-27' | 'gpt-4-turbo' | 'gpt-4-turbo-2024-04-09' | 'gpt-4-0125-preview' | 'gpt-4-turbo-preview' | 'gpt-4-1106-preview' | 'gpt-4-vision-preview' | 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-1106' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-16k-0613' - `name` string, nullable — The name of the assistant. The maximum length is 256 characters. - `description` string, nullable — The description of the assistant. The maximum length is 512 characters. - `instructions` string, nullable — The system instructions that the assistant uses. The maximum length is 256,000 characters. - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable — Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is supported for all models after `gpt-5.1-codex-max`. - `tools` union[] — A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - union - AssistantToolsCode - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter` - AssistantToolsFileSearch - `type` 'file_search', required — The type of tool being defined: `file_search` - `file_search` object — Overrides for the file search tool. - `max_num_results` integer — 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](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - `ranking_options` FileSearchRankingOptions — 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](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - `ranker` 'auto' | 'default_2024_08_21' — The ranker to use for the file search. If not specified will use the `auto` ranker. - `score_threshold` number, required — The score threshold for the file search. All values must be a floating point number between 0 and 1. - AssistantToolsFunction - `type` 'function', required — The type of tool being defined: `function` - `function` FunctionObject, required - `description` string — A description of what the function does, used by the model to choose when and how to call the function. - `name` string, required — 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. - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/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` boolean, nullable — 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](/docs/guides/function-calling). - `tool_resources` object, nullable — 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. - `code_interpreter` object - `file_ids` string[] — A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - `file_search` union - object - `vector_store_ids` string[], required — The [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - `vector_stores` object[] — A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. - `file_ids` string[] — A list of [file](/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - `chunking_strategy` union — The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - object — The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - … - object - … - `metadata` Metadata, nullable — 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 - `vector_store_ids` string[] — The [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - `vector_stores` object[], required — A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. - `file_ids` string[] — A list of [file](/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - `chunking_strategy` union — The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - object — The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - … - object - … - `metadata` Metadata, nullable — 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. - `metadata` Metadata, nullable — 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. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `response_format` union — Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs). Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - 'auto' — `auto` is the default value - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - ResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/docs/guides/structured-outputs). - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `json_schema` object, required — Structured Outputs configuration options, including a JSON Schema. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` ResponseFormatJsonSchemaSchema — The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](/docs/guides/structured-outputs). ## Response `200` OK - AssistantObject — Represents an `assistant` that can call the model and use tools. - `id` string, required — The identifier, which can be referenced in API endpoints. - `object` 'assistant', required — The object type, which is always `assistant`. - `created_at` integer, required — The Unix timestamp (in seconds) for when the assistant was created. - `name` string, nullable, required — The name of the assistant. The maximum length is 256 characters. - `description` string, nullable, required — The description of the assistant. The maximum length is 512 characters. - `model` string, required — ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - `instructions` string, nullable, required — The system instructions that the assistant uses. The maximum length is 256,000 characters. - `tools` union[], required — A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - union - AssistantToolsCode - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter` - AssistantToolsFileSearch - `type` 'file_search', required — The type of tool being defined: `file_search` - `file_search` object — Overrides for the file search tool. - `max_num_results` integer — 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](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - `ranking_options` FileSearchRankingOptions — 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](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - `ranker` 'auto' | 'default_2024_08_21' — The ranker to use for the file search. If not specified will use the `auto` ranker. - `score_threshold` number, required — The score threshold for the file search. All values must be a floating point number between 0 and 1. - AssistantToolsFunction - `type` 'function', required — The type of tool being defined: `function` - `function` FunctionObject, required - `description` string — A description of what the function does, used by the model to choose when and how to call the function. - `name` string, required — 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. - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/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` boolean, nullable — 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](/docs/guides/function-calling). - `tool_resources` object, nullable — 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. - `code_interpreter` object - `file_ids` string[] — A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - `file_search` object - `vector_store_ids` string[] — The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - `metadata` Metadata, nullable, required — 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. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. - `response_format` union — Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs). Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - 'auto' — `auto` is the default value - ResponseFormatText — Default response format. Used to generate text responses. - `type` 'text', required — The type of response format being defined. Always `text`. - ResponseFormatJsonObject — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required — The type of response format being defined. Always `json_object`. - ResponseFormatJsonSchema — JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/docs/guides/structured-outputs). - `type` 'json_schema', required — The type of response format being defined. Always `json_schema`. - `json_schema` object, required — Structured Outputs configuration options, including a JSON Schema. - `description` string — A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` ResponseFormatJsonSchemaSchema — The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). - `strict` boolean, nullable — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](/docs/guides/structured-outputs). --- [API](https://skmtc.net/openai/apis/openai-api-3.md) · [All operations](https://skmtc.net/openai/apis/openai-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openai/openai-api-3/versions/74cbcf73838f/schema)