resources/beta/subresources/threads/methods/create/index.md +0 −344 deleted
File Deleted View Diff
1## Create thread
2
3**post** `/threads`
4
5Create a thread.
6
7### Body Parameters
8
9- `messages: optional array of object { content, role, attachments, metadata }`
10
11 A list of [messages](/docs/api-reference/messages) to start the thread with.
12
13 - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam`
14
15 The text contents of the message.
16
17 - `TextContent = string`
18
19 The text contents of the message.
20
21 - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam`
22
23 An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models).
24
25 - `ImageFileContentBlock object { image_file, type }`
26
27 References an image [File](/docs/api-reference/files) in the content of a message.
28
29 - `image_file: ImageFile`
30
31 - `file_id: string`
32
33 The [File](/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.
34
35 - `detail: optional "auto" or "low" or "high"`
36
37 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`.
38
39 - `"auto"`
40
41 - `"low"`
42
43 - `"high"`
44
45 - `type: "image_file"`
46
47 Always `image_file`.
48
49 - `"image_file"`
50
51 - `ImageURLContentBlock object { image_url, type }`
52
53 References an image URL in the content of a message.
54
55 - `image_url: ImageURL`
56
57 - `url: string`
58
59 The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.
60
61 - `detail: optional "auto" or "low" or "high"`
62
63 Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto`
64
65 - `"auto"`
66
67 - `"low"`
68
69 - `"high"`
70
71 - `type: "image_url"`
72
73 The type of the content part.
74
75 - `"image_url"`
76
77 - `TextContentBlockParam object { text, type }`
78
79 The text content that is part of a message.
80
81 - `text: string`
82
83 Text content to be sent to the model
84
85 - `type: "text"`
86
87 Always `text`.
88
89 - `"text"`
90
91 - `role: "user" or "assistant"`
92
93 The role of the entity that is creating the message. Allowed values include:
94
95 - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
96 - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.
97
98 - `"user"`
99
100 - `"assistant"`
101
102 - `attachments: optional array of object { file_id, tools } or null`
103
104 A list of files attached to the message, and the tools they should be added to.
105
106 - `file_id: optional string`
107
108 The ID of the file to attach to the message.
109
110 - `tools: optional array of CodeInterpreterTool or object { type }`
111
112 The tools to add this file to.
113
114 - `CodeInterpreterTool object { type }`
115
116 - `type: "code_interpreter"`
117
118 The type of tool being defined: `code_interpreter`
119
120 - `"code_interpreter"`
121
122 - `FileSearchTool object { type }`
123
124 - `type: "file_search"`
125
126 The type of tool being defined: `file_search`
127
128 - `"file_search"`
129
130 - `metadata: optional Metadata or null`
131
132 Set of 16 key-value pairs that can be attached to an object. This can be
133 useful for storing additional information about the object in a structured
134 format, and querying for objects via API or the dashboard.
135
136 Keys are strings with a maximum length of 64 characters. Values are strings
137 with a maximum length of 512 characters.
138
139- `metadata: optional Metadata or null`
140
141 Set of 16 key-value pairs that can be attached to an object. This can be
142 useful for storing additional information about the object in a structured
143 format, and querying for objects via API or the dashboard.
144
145 Keys are strings with a maximum length of 64 characters. Values are strings
146 with a maximum length of 512 characters.
147
148- `tool_resources: optional object { code_interpreter, file_search } or null`
149
150 A set of resources that are made available to the assistant's tools in this thread. 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.
151
152 - `code_interpreter: optional object { file_ids }`
153
154 - `file_ids: optional array of string`
155
156 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.
157
158 - `file_search: optional object { vector_store_ids, vector_stores }`
159
160 - `vector_store_ids: optional array of string`
161
162 The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread.
163
164 - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }`
165
166 A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread.
167
168 - `chunking_strategy: optional object { type } or object { static, type }`
169
170 The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy.
171
172 - `Auto object { type }`
173
174 The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`.
175
176 - `type: "auto"`
177
178 Always `auto`.
179
180 - `"auto"`
181
182 - `Static object { static, type }`
183
184 - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }`
185
186 - `chunk_overlap_tokens: number`
187
188 The number of tokens that overlap between chunks. The default value is `400`.
189
190 Note that the overlap must not exceed half of `max_chunk_size_tokens`.
191
192 - `max_chunk_size_tokens: number`
193
194 The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`.
195
196 - `type: "static"`
197
198 Always `static`.
199
200 - `"static"`
201
202 - `file_ids: optional array of string`
203
204 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.
205
206 - `metadata: optional Metadata or null`
207
208 Set of 16 key-value pairs that can be attached to an object. This can be
209 useful for storing additional information about the object in a structured
210 format, and querying for objects via API or the dashboard.
211
212 Keys are strings with a maximum length of 64 characters. Values are strings
213 with a maximum length of 512 characters.
214
215### Returns
216
217- `Thread object { id, created_at, metadata, 2 more }`
218
219 Represents a thread that contains [messages](/docs/api-reference/messages).
220
221 - `id: string`
222
223 The identifier, which can be referenced in API endpoints.
224
225 - `created_at: number`
226
227 The Unix timestamp (in seconds) for when the thread was created.
228
229 - `metadata: Metadata or null`
230
231 Set of 16 key-value pairs that can be attached to an object. This can be
232 useful for storing additional information about the object in a structured
233 format, and querying for objects via API or the dashboard.
234
235 Keys are strings with a maximum length of 64 characters. Values are strings
236 with a maximum length of 512 characters.
237
238 - `object: "thread"`
239
240 The object type, which is always `thread`.
241
242 - `"thread"`
243
244 - `tool_resources: object { code_interpreter, file_search } or null`
245
246 A set of resources that are made available to the assistant's tools in this thread. 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.
247
248 - `code_interpreter: optional object { file_ids }`
249
250 - `file_ids: optional array of string`
251
252 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.
253
254 - `file_search: optional object { vector_store_ids }`
255
256 - `vector_store_ids: optional array of string`
257
258 The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread.
259
260### Example
261
262```http
263curl https://api.openai.com/v1/threads \
264 -X POST \
265 -H 'OpenAI-Beta: assistants=v2' \
266 -H "Authorization: Bearer $OPENAI_API_KEY"
267```
268
269#### Response
270
271```json
272{
273 "id": "id",
274 "created_at": 0,
275 "metadata": {
276 "foo": "string"
277 },
278 "object": "thread",
279 "tool_resources": {
280 "code_interpreter": {
281 "file_ids": [
282 "string"
283 ]
284 },
285 "file_search": {
286 "vector_store_ids": [
287 "string"
288 ]
289 }
290 }
291}
292```
293
294### Empty
295
296```http
297curl https://api.openai.com/v1/threads \
298 -H "Content-Type: application/json" \
299 -H "Authorization: Bearer $OPENAI_API_KEY" \
300 -H "OpenAI-Beta: assistants=v2" \
301 -d ''
302```
303
304#### Response
305
306```json
307{
308 "id": "thread_abc123",
309 "object": "thread",
310 "created_at": 1699012949,
311 "metadata": {},
312 "tool_resources": {}
313}
314```
315
316### Messages
317
318```http
319curl https://api.openai.com/v1/threads \
320-H "Content-Type: application/json" \
321-H "Authorization: Bearer $OPENAI_API_KEY" \
322-H "OpenAI-Beta: assistants=v2" \
323-d '{
324 "messages": [{
325 "role": "user",
326 "content": "Hello, what is AI?"
327 }, {
328 "role": "user",
329 "content": "How does AI work? Explain it in simple terms."
330 }]
331 }'
332```
333
334#### Response
335
336```json
337{
338 "id": "thread_abc123",
339 "object": "thread",
340 "created_at": 1699014083,
341 "metadata": {},
342 "tool_resources": {}
343}
344```