resources/beta/subresources/assistants/methods/update/index.md +0 −645 deleted
File Deleted View Diff
1## Modify assistant
2
3**post** `/assistants/{assistant_id}`
4
5Modifies an assistant.
6
7### Path Parameters
8
9- `assistant_id: string`
10
11### Body Parameters
12
13- `description: optional string or null`
14
15 The description of the assistant. The maximum length is 512 characters.
16
17- `instructions: optional string or null`
18
19 The system instructions that the assistant uses. The maximum length is 256,000 characters.
20
21- `metadata: optional Metadata or null`
22
23 Set of 16 key-value pairs that can be attached to an object. This can be
24 useful for storing additional information about the object in a structured
25 format, and querying for objects via API or the dashboard.
26
27 Keys are strings with a maximum length of 64 characters. Values are strings
28 with a maximum length of 512 characters.
29
30- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more`
31
32 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.
33
34 - `string`
35
36 - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more`
37
38 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.
39
40 - `"gpt-5"`
41
42 - `"gpt-5-mini"`
43
44 - `"gpt-5-nano"`
45
46 - `"gpt-5-2025-08-07"`
47
48 - `"gpt-5-mini-2025-08-07"`
49
50 - `"gpt-5-nano-2025-08-07"`
51
52 - `"gpt-4.1"`
53
54 - `"gpt-4.1-mini"`
55
56 - `"gpt-4.1-nano"`
57
58 - `"gpt-4.1-2025-04-14"`
59
60 - `"gpt-4.1-mini-2025-04-14"`
61
62 - `"gpt-4.1-nano-2025-04-14"`
63
64 - `"o3-mini"`
65
66 - `"o3-mini-2025-01-31"`
67
68 - `"o1"`
69
70 - `"o1-2024-12-17"`
71
72 - `"gpt-4o"`
73
74 - `"gpt-4o-2024-11-20"`
75
76 - `"gpt-4o-2024-08-06"`
77
78 - `"gpt-4o-2024-05-13"`
79
80 - `"gpt-4o-mini"`
81
82 - `"gpt-4o-mini-2024-07-18"`
83
84 - `"gpt-4.5-preview"`
85
86 - `"gpt-4.5-preview-2025-02-27"`
87
88 - `"gpt-4-turbo"`
89
90 - `"gpt-4-turbo-2024-04-09"`
91
92 - `"gpt-4-0125-preview"`
93
94 - `"gpt-4-turbo-preview"`
95
96 - `"gpt-4-1106-preview"`
97
98 - `"gpt-4-vision-preview"`
99
100 - `"gpt-4"`
101
102 - `"gpt-4-0314"`
103
104 - `"gpt-4-0613"`
105
106 - `"gpt-4-32k"`
107
108 - `"gpt-4-32k-0314"`
109
110 - `"gpt-4-32k-0613"`
111
112 - `"gpt-3.5-turbo"`
113
114 - `"gpt-3.5-turbo-16k"`
115
116 - `"gpt-3.5-turbo-0613"`
117
118 - `"gpt-3.5-turbo-1106"`
119
120 - `"gpt-3.5-turbo-0125"`
121
122 - `"gpt-3.5-turbo-16k-0613"`
123
124- `name: optional string or null`
125
126 The name of the assistant. The maximum length is 256 characters.
127
128- `reasoning_effort: optional ReasoningEffort or null`
129
130 Constrains effort on reasoning for reasoning models. Currently supported
131 values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
132 Reducing reasoning effort can result in faster responses and fewer tokens
133 used on reasoning in a response. Not all reasoning models support every
134 value. See the
135 [reasoning guide](https://platform.openai.com/docs/guides/reasoning)
136 for model-specific support.
137
138 - `"none"`
139
140 - `"minimal"`
141
142 - `"low"`
143
144 - `"medium"`
145
146 - `"high"`
147
148 - `"xhigh"`
149
150 - `"max"`
151
152- `response_format: optional AssistantResponseFormatOption or null`
153
154 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`.
155
156 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).
157
158 Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
159
160 **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.
161
162 - `"auto"`
163
164 `auto` is the default value
165
166 - `"auto"`
167
168 - `ResponseFormatText object { type }`
169
170 Default response format. Used to generate text responses.
171
172 - `type: "text"`
173
174 The type of response format being defined. Always `text`.
175
176 - `"text"`
177
178 - `ResponseFormatJSONObject object { type }`
179
180 JSON object response format. An older method of generating JSON responses.
181 Using `json_schema` is recommended for models that support it. Note that the
182 model will not generate JSON without a system or user message instructing it
183 to do so.
184
185 - `type: "json_object"`
186
187 The type of response format being defined. Always `json_object`.
188
189 - `"json_object"`
190
191 - `ResponseFormatJSONSchema object { json_schema, type }`
192
193 JSON Schema response format. Used to generate structured JSON responses.
194 Learn more about [Structured Outputs](/docs/guides/structured-outputs).
195
196 - `json_schema: object { name, description, schema, strict }`
197
198 Structured Outputs configuration options, including a JSON Schema.
199
200 - `name: string`
201
202 The name of the response format. Must be a-z, A-Z, 0-9, or contain
203 underscores and dashes, with a maximum length of 64.
204
205 - `description: optional string`
206
207 A description of what the response format is for, used by the model to
208 determine how to respond in the format.
209
210 - `schema: optional map[unknown]`
211
212 The schema for the response format, described as a JSON Schema object.
213 Learn how to build JSON schemas [here](https://json-schema.org/).
214
215 - `strict: optional boolean or null`
216
217 Whether to enable strict schema adherence when generating the output.
218 If set to true, the model will always follow the exact schema defined
219 in the `schema` field. Only a subset of JSON Schema is supported when
220 `strict` is `true`. To learn more, read the [Structured Outputs
221 guide](/docs/guides/structured-outputs).
222
223 - `type: "json_schema"`
224
225 The type of response format being defined. Always `json_schema`.
226
227 - `"json_schema"`
228
229- `temperature: optional number or null`
230
231 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.
232
233- `tool_resources: optional object { code_interpreter, file_search } or null`
234
235 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.
236
237 - `code_interpreter: optional object { file_ids }`
238
239 - `file_ids: optional array of string`
240
241 Overrides the 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.
242
243 - `file_search: optional object { vector_store_ids }`
244
245 - `vector_store_ids: optional array of string`
246
247 Overrides 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.
248
249- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool`
250
251 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`.
252
253 - `CodeInterpreterTool object { type }`
254
255 - `type: "code_interpreter"`
256
257 The type of tool being defined: `code_interpreter`
258
259 - `"code_interpreter"`
260
261 - `FileSearchTool object { type, file_search }`
262
263 - `type: "file_search"`
264
265 The type of tool being defined: `file_search`
266
267 - `"file_search"`
268
269 - `file_search: optional object { max_num_results, ranking_options }`
270
271 Overrides for the file search tool.
272
273 - `max_num_results: optional number`
274
275 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.
276
277 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.
278
279 - `ranking_options: optional object { score_threshold, ranker }`
280
281 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.
282
283 See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.
284
285 - `score_threshold: number`
286
287 The score threshold for the file search. All values must be a floating point number between 0 and 1.
288
289 - `ranker: optional "auto" or "default_2024_08_21"`
290
291 The ranker to use for the file search. If not specified will use the `auto` ranker.
292
293 - `"auto"`
294
295 - `"default_2024_08_21"`
296
297 - `FunctionTool object { function, type }`
298
299 - `function: FunctionDefinition`
300
301 - `name: string`
302
303 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.
304
305 - `description: optional string`
306
307 A description of what the function does, used by the model to choose when and how to call the function.
308
309 - `parameters: optional FunctionParameters`
310
311 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.
312
313 Omitting `parameters` defines a function with an empty parameter list.
314
315 - `strict: optional boolean or null`
316
317 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).
318
319 - `type: "function"`
320
321 The type of tool being defined: `function`
322
323 - `"function"`
324
325- `top_p: optional number or null`
326
327 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.
328
329 We generally recommend altering this or temperature but not both.
330
331### Returns
332
333- `Assistant object { id, created_at, description, 10 more }`
334
335 Represents an `assistant` that can call the model and use tools.
336
337 - `id: string`
338
339 The identifier, which can be referenced in API endpoints.
340
341 - `created_at: number`
342
343 The Unix timestamp (in seconds) for when the assistant was created.
344
345 - `description: string or null`
346
347 The description of the assistant. The maximum length is 512 characters.
348
349 - `instructions: string or null`
350
351 The system instructions that the assistant uses. The maximum length is 256,000 characters.
352
353 - `metadata: Metadata or null`
354
355 Set of 16 key-value pairs that can be attached to an object. This can be
356 useful for storing additional information about the object in a structured
357 format, and querying for objects via API or the dashboard.
358
359 Keys are strings with a maximum length of 64 characters. Values are strings
360 with a maximum length of 512 characters.
361
362 - `model: string`
363
364 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.
365
366 - `name: string or null`
367
368 The name of the assistant. The maximum length is 256 characters.
369
370 - `object: "assistant"`
371
372 The object type, which is always `assistant`.
373
374 - `"assistant"`
375
376 - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool`
377
378 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`.
379
380 - `CodeInterpreterTool object { type }`
381
382 - `type: "code_interpreter"`
383
384 The type of tool being defined: `code_interpreter`
385
386 - `"code_interpreter"`
387
388 - `FileSearchTool object { type, file_search }`
389
390 - `type: "file_search"`
391
392 The type of tool being defined: `file_search`
393
394 - `"file_search"`
395
396 - `file_search: optional object { max_num_results, ranking_options }`
397
398 Overrides for the file search tool.
399
400 - `max_num_results: optional number`
401
402 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.
403
404 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.
405
406 - `ranking_options: optional object { score_threshold, ranker }`
407
408 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.
409
410 See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.
411
412 - `score_threshold: number`
413
414 The score threshold for the file search. All values must be a floating point number between 0 and 1.
415
416 - `ranker: optional "auto" or "default_2024_08_21"`
417
418 The ranker to use for the file search. If not specified will use the `auto` ranker.
419
420 - `"auto"`
421
422 - `"default_2024_08_21"`
423
424 - `FunctionTool object { function, type }`
425
426 - `function: FunctionDefinition`
427
428 - `name: string`
429
430 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.
431
432 - `description: optional string`
433
434 A description of what the function does, used by the model to choose when and how to call the function.
435
436 - `parameters: optional FunctionParameters`
437
438 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.
439
440 Omitting `parameters` defines a function with an empty parameter list.
441
442 - `strict: optional boolean or null`
443
444 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).
445
446 - `type: "function"`
447
448 The type of tool being defined: `function`
449
450 - `"function"`
451
452 - `response_format: optional AssistantResponseFormatOption or null`
453
454 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`.
455
456 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).
457
458 Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
459
460 **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.
461
462 - `"auto"`
463
464 `auto` is the default value
465
466 - `"auto"`
467
468 - `ResponseFormatText object { type }`
469
470 Default response format. Used to generate text responses.
471
472 - `type: "text"`
473
474 The type of response format being defined. Always `text`.
475
476 - `"text"`
477
478 - `ResponseFormatJSONObject object { type }`
479
480 JSON object response format. An older method of generating JSON responses.
481 Using `json_schema` is recommended for models that support it. Note that the
482 model will not generate JSON without a system or user message instructing it
483 to do so.
484
485 - `type: "json_object"`
486
487 The type of response format being defined. Always `json_object`.
488
489 - `"json_object"`
490
491 - `ResponseFormatJSONSchema object { json_schema, type }`
492
493 JSON Schema response format. Used to generate structured JSON responses.
494 Learn more about [Structured Outputs](/docs/guides/structured-outputs).
495
496 - `json_schema: object { name, description, schema, strict }`
497
498 Structured Outputs configuration options, including a JSON Schema.
499
500 - `name: string`
501
502 The name of the response format. Must be a-z, A-Z, 0-9, or contain
503 underscores and dashes, with a maximum length of 64.
504
505 - `description: optional string`
506
507 A description of what the response format is for, used by the model to
508 determine how to respond in the format.
509
510 - `schema: optional map[unknown]`
511
512 The schema for the response format, described as a JSON Schema object.
513 Learn how to build JSON schemas [here](https://json-schema.org/).
514
515 - `strict: optional boolean or null`
516
517 Whether to enable strict schema adherence when generating the output.
518 If set to true, the model will always follow the exact schema defined
519 in the `schema` field. Only a subset of JSON Schema is supported when
520 `strict` is `true`. To learn more, read the [Structured Outputs
521 guide](/docs/guides/structured-outputs).
522
523 - `type: "json_schema"`
524
525 The type of response format being defined. Always `json_schema`.
526
527 - `"json_schema"`
528
529 - `temperature: optional number or null`
530
531 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.
532
533 - `tool_resources: optional object { code_interpreter, file_search } or null`
534
535 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.
536
537 - `code_interpreter: optional object { file_ids }`
538
539 - `file_ids: optional array of string`
540
541 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.
542
543 - `file_search: optional object { vector_store_ids }`
544
545 - `vector_store_ids: optional array of string`
546
547 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.
548
549 - `top_p: optional number or null`
550
551 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.
552
553 We generally recommend altering this or temperature but not both.
554
555### Example
556
557```http
558curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \
559 -H 'Content-Type: application/json' \
560 -H 'OpenAI-Beta: assistants=v2' \
561 -H "Authorization: Bearer $OPENAI_API_KEY" \
562 -d '{
563 "temperature": 1,
564 "top_p": 1
565 }'
566```
567
568#### Response
569
570```json
571{
572 "id": "id",
573 "created_at": 0,
574 "description": "description",
575 "instructions": "instructions",
576 "metadata": {
577 "foo": "string"
578 },
579 "model": "model",
580 "name": "name",
581 "object": "assistant",
582 "tools": [
583 {
584 "type": "code_interpreter"
585 }
586 ],
587 "response_format": "auto",
588 "temperature": 1,
589 "tool_resources": {
590 "code_interpreter": {
591 "file_ids": [
592 "string"
593 ]
594 },
595 "file_search": {
596 "vector_store_ids": [
597 "string"
598 ]
599 }
600 },
601 "top_p": 1
602}
603```
604
605### Example
606
607```http
608curl https://api.openai.com/v1/assistants/asst_abc123 \
609 -H "Content-Type: application/json" \
610 -H "Authorization: Bearer $OPENAI_API_KEY" \
611 -H "OpenAI-Beta: assistants=v2" \
612 -d '{
613 "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
614 "tools": [{"type": "file_search"}],
615 "model": "gpt-4o"
616 }'
617```
618
619#### Response
620
621```json
622{
623 "id": "asst_123",
624 "object": "assistant",
625 "created_at": 1699009709,
626 "name": "HR Helper",
627 "description": null,
628 "model": "gpt-4o",
629 "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
630 "tools": [
631 {
632 "type": "file_search"
633 }
634 ],
635 "tool_resources": {
636 "file_search": {
637 "vector_store_ids": []
638 }
639 },
640 "metadata": {},
641 "top_p": 1.0,
642 "temperature": 1.0,
643 "response_format": "auto"
644}
645```