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