---
title: "Create an assistant with a model and instructions."
method: POST
path: "/assistants"
tags: ["Assistants"]
---

# Create an assistant with a model and instructions.

`POST /assistants`

## 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
    - '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-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` 'low' | 'medium' | 'high', nullable — **o1 and o3-mini models only** Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
  - `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
      - object
        - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter`
      - object
        - `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.
      - object
        - `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. There can be a maximum of 10000 files in a vector store.
          - `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. There can be a maximum of 10000 files in a vector store.
          - `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
    - 'auto', nullable — `auto` is the default value
    - object, nullable
      - `type` 'text', required — The type of response format being defined: `text`
    - object, nullable
      - `type` 'json_object', required — The type of response format being defined: `json_object`
    - object, nullable
      - `type` 'json_schema', required — The type of response format being defined: `json_schema`
      - `json_schema` object, required
        - `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.
        - `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
      - object
        - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter`
      - object
        - `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.
      - object
        - `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
    - 'auto', nullable — `auto` is the default value
    - object, nullable
      - `type` 'text', required — The type of response format being defined: `text`
    - object, nullable
      - `type` 'json_object', required — The type of response format being defined: `json_object`
    - object, nullable
      - `type` 'json_schema', required — The type of response format being defined: `json_schema`
      - `json_schema` object, required
        - `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.
        - `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).

## Changes

- **2025-02-11** `96060afbb5b9` — 1 breaking, 2 info
  - removed `subschema #2` from the `model` request property `anyOf` list
  - added the new optional request property `reasoning_effort`
  - added `#/components/schemas/AssistantSupportedModels` to the `model` request property `anyOf` list
- **2025-01-31** `fc164a27fdb9` — 3 breaking, 3 info
  - added `#/components/schemas/AssistantsApiResponseFormatOption, subschema #2` to the `response_format` request property `allOf` list
  - the request property `response_format` became not nullable
  - removed `#/components/schemas/ResponseFormatText, #/components/schemas/ResponseFormatJsonObject, #/components/schemas/ResponseFormatJsonSchema, subschema #1` from the `response_format` request property `oneOf` list
  - the request property `tool_resources/file_search/vector_stores/items/metadata` became nullable
  - …2 more
- **2025-01-31** `15156e46769c` — 2 breaking, 1 warning, 3 info
  - the response property `response_format` became nullable for the status `200`
  - added `#/components/schemas/ResponseFormatText, #/components/schemas/ResponseFormatJsonObject, #/components/schemas/ResponseFormatJsonSchema, subschema #1` to the `response_format` response property `oneOf` list for the response status `200`
  - removed `#/components/schemas/AssistantsApiResponseFormatOption, subschema #2` from the `response_format` request property `allOf` list
  - the request property `response_format` became nullable
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/openai/apis/openapi/changes/assistants/post.md)

---

[API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openai/openapi/revisions/96060afbb5b9/schema)