Documentation 2026-08-03 18:01 UTC to 2026-08-04 22:59 UTC

23 23 

24For example, to create an Assistant that can create data visualization based on a `.csv` file, first upload a file.24For example, to create an Assistant that can create data visualization based on a `.csv` file, first upload a file.

25 25 

26```python

27file = client.files.create(

28 file=open("revenue-forecast.csv", "rb"), purpose="assistants"

29)

30```

31 

32```javascript26```javascript

33const file = await openai.files.create({27const file = await openai.files.create({

34 file: fs.createReadStream("revenue-forecast.csv"),28 file: fs.createReadStream("revenue-forecast.csv"),

36});30});

37```31```

38 32 

33```python

34file = client.files.create(

35 file=open("revenue-forecast.csv", "rb"), purpose="assistants"

36)

37```

38 

39```bash39```bash

40curl https://api.openai.com/v1/files \40curl https://api.openai.com/v1/files \

41 -H "Authorization: Bearer $OPENAI_API_KEY" \41 -H "Authorization: Bearer $OPENAI_API_KEY" \

46 46 

47Then, create the Assistant with the `code_interpreter` tool enabled and provide the file as a resource to the tool.47Then, create the Assistant with the `code_interpreter` tool enabled and provide the file as a resource to the tool.

48 48 

49```python

50assistant = client.beta.assistants.create(

51 name="Data visualizer",

52 description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

53 model="gpt-4o",

54 tools=[{"type": "code_interpreter"}],

55 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

56)

57```

58 

59```javascript49```javascript

60const assistant = await openai.beta.assistants.create({50const assistant = await openai.beta.assistants.create({

61 name: "Data visualizer",51 name: "Data visualizer",

71});61});

72```62```

73 63 

64```python

65assistant = client.beta.assistants.create(

66 name="Data visualizer",

67 description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

68 model="gpt-4o",

69 tools=[{"type": "code_interpreter"}],

70 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

71)

72```

73 

74```bash74```bash

75curl https://api.openai.com/v1/assistants \75curl https://api.openai.com/v1/assistants \

76 -H "Authorization: Bearer $OPENAI_API_KEY" \76 -H "Authorization: Bearer $OPENAI_API_KEY" \

100 100 

101You can create a Thread with an initial list of Messages like this:101You can create a Thread with an initial list of Messages like this:

102 102 

103```python

104thread = client.beta.threads.create(

105 messages=[

106 {

107 "role": "user",

108 "content": "Create 3 data visualizations based on the trends in this file.",

109 "attachments": [

110 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

111 ],

112 }

113 ]

114)

115```

116 

117```javascript103```javascript

118const thread = await openai.beta.threads.create({104const thread = await openai.beta.threads.create({

119 messages: [105 messages: [

131});117});

132```118```

133 119 

120```python

121thread = client.beta.threads.create(

122 messages=[

123 {

124 "role": "user",

125 "content": "Create 3 data visualizations based on the trends in this file.",

126 "attachments": [

127 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

128 ],

129 }

130 ]

131)

132```

133 

134```bash134```bash

135curl https://api.openai.com/v1/threads \135curl https://api.openai.com/v1/threads \

136 -H "Authorization: Bearer $OPENAI_API_KEY" \136 -H "Authorization: Bearer $OPENAI_API_KEY" \

161 161 

162Tools cannot access image content unless specified. To pass image files to Code Interpreter, add the file ID in the message `attachments` list to allow the tool to read and analyze the input. Image URLs cannot be downloaded in Code Interpreter today.162Tools cannot access image content unless specified. To pass image files to Code Interpreter, add the file ID in the message `attachments` list to allow the tool to read and analyze the input. Image URLs cannot be downloaded in Code Interpreter today.

163 163 

164```python

165file = client.files.create(file=open("myimage.png", "rb"), purpose="vision")

166thread = client.beta.threads.create(

167 messages=[

168 {

169 "role": "user",

170 "content": [

171 {

172 "type": "text",

173 "text": "What is the difference between these images?",

174 },

175 {

176 "type": "image_url",

177 "image_url": {

178 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"

179 },

180 },

181 {"type": "image_file", "image_file": {"file_id": file.id}},

182 ],

183 }

184 ]

185)

186```

187 

188```javascript164```javascript

189import fs from "fs";165import fs from "fs";

190 166 

217});193});

218```194```

219 195 

196```python

197file = client.files.create(file=open("myimage.png", "rb"), purpose="vision")

198thread = client.beta.threads.create(

199 messages=[

200 {

201 "role": "user",

202 "content": [

203 {

204 "type": "text",

205 "text": "What is the difference between these images?",

206 },

207 {

208 "type": "image_url",

209 "image_url": {

210 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"

211 },

212 },

213 {"type": "image_file", "image_file": {"file_id": file.id}},

214 ],

215 }

216 ]

217)

218```

219 

220```bash220```bash

221# Upload a file with an "vision" purpose221# Upload a file with an "vision" purpose

222curl https://api.openai.com/v1/files \222curl https://api.openai.com/v1/files \

261- `low` will enable the "low res" mode. The model will receive a low-res 512px x 512px version of the image, and represent the image with a budget of 85 tokens. This allows the API to return faster responses and consume fewer input tokens for use cases that do not require high detail.261- `low` will enable the "low res" mode. The model will receive a low-res 512px x 512px version of the image, and represent the image with a budget of 85 tokens. This allows the API to return faster responses and consume fewer input tokens for use cases that do not require high detail.

262- `high` will enable "high res" mode, which first allows the model to see the low res image and then creates detailed crops of input images based on the input image size. Use the [pricing calculator](https://openai.com/api/pricing/) to see token counts for various image sizes.262- `high` will enable "high res" mode, which first allows the model to see the low res image and then creates detailed crops of input images based on the input image size. Use the [pricing calculator](https://openai.com/api/pricing/) to see token counts for various image sizes.

263 263 

264```python

265thread = client.beta.threads.create(

266 messages=[

267 {

268 "role": "user",

269 "content": [

270 {"type": "text", "text": "What is this an image of?"},

271 {

272 "type": "image_url",

273 "image_url": {

274 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

275 "detail": "high",

276 },

277 },

278 ],

279 }

280 ]

281)

282```

283 

284```javascript264```javascript

285const thread = await openai.beta.threads.create({265const thread = await openai.beta.threads.create({

286 messages: [266 messages: [

304});284});

305```285```

306 286 

287```python

288thread = client.beta.threads.create(

289 messages=[

290 {

291 "role": "user",

292 "content": [

293 {"type": "text", "text": "What is this an image of?"},

294 {

295 "type": "image_url",

296 "image_url": {

297 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

298 "detail": "high",

299 },

300 },

301 ],

302 }

303 ]

304)

305```

306 

307```bash307```bash

308curl https://api.openai.com/v1/threads \308curl https://api.openai.com/v1/threads \

309 -H "Authorization: Bearer $OPENAI_API_KEY" \309 -H "Authorization: Bearer $OPENAI_API_KEY" \

415 415 

416When you have all the context you need from your user in the Thread, you can run the Thread with an Assistant of your choice.416When you have all the context you need from your user in the Thread, you can run the Thread with an Assistant of your choice.

417 417 

418```javascript

419const run = await openai.beta.threads.runs.create(thread.id, {

420 assistant_id: assistant.id,

421});

422```

423 

418```python424```python

419run = client.beta.threads.runs.create(425run = client.beta.threads.runs.create(

420 thread_id=thread.id,426 thread_id=thread.id,

422)428)

423```429```

424 430 

425```javascript

426const run = await openai.beta.threads.runs.create(thread.id, {

427 assistant_id: assistant.id,

428});

429```

430 

431```bash431```bash

432curl https://api.openai.com/v1/threads/THREAD_ID/runs \432curl https://api.openai.com/v1/threads/THREAD_ID/runs \

433 -H "Authorization: Bearer $OPENAI_API_KEY" \433 -H "Authorization: Bearer $OPENAI_API_KEY" \

441 441 

442By default, a Run will use the `model` and `tools` configuration specified in Assistant object, but you can override most of these when creating the Run for added flexibility:442By default, a Run will use the `model` and `tools` configuration specified in Assistant object, but you can override most of these when creating the Run for added flexibility:

443 443 

444```javascript

445const run = await openai.beta.threads.runs.create(thread.id, {

446 assistant_id: assistant.id,

447 model: "gpt-4o",

448 instructions: "New instructions that override the Assistant instructions",

449 tools: [{ type: "code_interpreter" }, { type: "file_search" }],

450});

451```

452 

444```python453```python

445run = client.beta.threads.runs.create(454run = client.beta.threads.runs.create(

446 thread_id=thread.id,455 thread_id=thread.id,

451)460)

452```461```

453 462 

454```javascript

455const run = await openai.beta.threads.runs.create(thread.id, {

456 assistant_id: assistant.id,

457 model: "gpt-4o",

458 instructions: "New instructions that override the Assistant instructions",

459 tools: [{ type: "code_interpreter" }, { type: "file_search" }],

460});

461```

462 

463```bash463```bash

464curl https://api.openai.com/v1/threads/THREAD_ID/runs \464curl https://api.openai.com/v1/threads/THREAD_ID/runs \

465 -H "Authorization: Bearer $OPENAI_API_KEY" \465 -H "Authorization: Bearer $OPENAI_API_KEY" \

18 18 

19Pass `code_interpreter` in the `tools` parameter of the Assistant object to enable Code Interpreter:19Pass `code_interpreter` in the `tools` parameter of the Assistant object to enable Code Interpreter:

20 20 

21```python

22assistant = client.beta.assistants.create(

23 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

24 model="gpt-4o",

25 tools=[{"type": "code_interpreter"}],

26)

27```

28 

29```javascript21```javascript

30const assistant = await openai.beta.assistants.create({22const assistant = await openai.beta.assistants.create({

31 instructions:23 instructions:

35});27});

36```28```

37 29 

30```python

31assistant = client.beta.assistants.create(

32 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

33 model="gpt-4o",

34 tools=[{"type": "code_interpreter"}],

35)

36```

37 

38```bash38```bash

39curl https://api.openai.com/v1/assistants \39curl https://api.openai.com/v1/assistants \

40 -u :$OPENAI_API_KEY \40 -u :$OPENAI_API_KEY \

56 56 

57Files that are passed at the Assistant level are accessible by all Runs with this Assistant:57Files that are passed at the Assistant level are accessible by all Runs with this Assistant:

58 58 

59```python

60# Upload a file with an "assistants" purpose

61file = client.files.create(file=open("mydata.csv", "rb"), purpose="assistants")

62 

63# Create an assistant using the file ID

64assistant = client.beta.assistants.create(

65 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

66 model="gpt-4o",

67 tools=[{"type": "code_interpreter"}],

68 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

69)

70```

71 

72```javascript59```javascript

73// Upload a file with an "assistants" purpose60// Upload a file with an "assistants" purpose

74const file = await openai.files.create({61const file = await openai.files.create({

90});77});

91```78```

92 79 

80```python

81# Upload a file with an "assistants" purpose

82file = client.files.create(file=open("mydata.csv", "rb"), purpose="assistants")

83 

84# Create an assistant using the file ID

85assistant = client.beta.assistants.create(

86 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

87 model="gpt-4o",

88 tools=[{"type": "code_interpreter"}],

89 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

90)

91```

92 

93```bash93```bash

94# Upload a file with an "assistants" purpose94# Upload a file with an "assistants" purpose

95curl https://api.openai.com/v1/files \95curl https://api.openai.com/v1/files \

117 117 

118Files can also be passed at the Thread level. These files are only accessible in the specific Thread. Upload the File using the [File upload](https://developers.openai.com/api/reference/resources/files/methods/create) endpoint and then pass the File ID as part of the Message creation request:118Files can also be passed at the Thread level. These files are only accessible in the specific Thread. Upload the File using the [File upload](https://developers.openai.com/api/reference/resources/files/methods/create) endpoint and then pass the File ID as part of the Message creation request:

119 119 

120```python

121thread = client.beta.threads.create(

122 messages=[

123 {

124 "role": "user",

125 "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

126 "attachments": [

127 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

128 ],

129 }

130 ]

131)

132```

133 

134```javascript120```javascript

135const thread = await openai.beta.threads.create({121const thread = await openai.beta.threads.create({

136 messages: [122 messages: [

148});134});

149```135```

150 136 

137```python

138thread = client.beta.threads.create(

139 messages=[

140 {

141 "role": "user",

142 "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",

143 "attachments": [

144 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

145 ],

146 }

147 ]

148)

149```

150 

151```bash151```bash

152curl https://api.openai.com/v1/threads/thread_abc123/messages \152curl https://api.openai.com/v1/threads/thread_abc123/messages \

153 -u :$OPENAI_API_KEY \153 -u :$OPENAI_API_KEY \

198 198 

199The file content can then be downloaded by passing the file ID to the Files API:199The file content can then be downloaded by passing the file ID to the Files API:

200 200 

201```python

202import os

203 

204from openai import OpenAI

205 

206file_id = os.environ["OPENAI_FILE_ID"]

207client = OpenAI()

208 

209image_data = client.files.content(file_id)

210image_data_bytes = image_data.read()

211 

212with open("./my-image.png", "wb") as file:

213 file.write(image_data_bytes)

214```

215 

216```javascript201```javascript

217import fs from "fs";202import fs from "fs";

218import OpenAI from "openai";203import OpenAI from "openai";

235main();220main();

236```221```

237 222 

223```python

224import os

225 

226from openai import OpenAI

227 

228file_id = os.environ["OPENAI_FILE_ID"]

229client = OpenAI()

230 

231image_data = client.files.content(file_id)

232image_data_bytes = image_data.read()

233 

234with open("./my-image.png", "wb") as file:

235 file.write(image_data_bytes)

236```

237 

238```bash238```bash

239curl https://api.openai.com/v1/files/file-abc123/content \239curl https://api.openai.com/v1/files/file-abc123/content \

240 -H "Authorization: Bearer $OPENAI_API_KEY" \240 -H "Authorization: Bearer $OPENAI_API_KEY" \

273 273 

274By listing the steps of a Run that called Code Interpreter, you can inspect the code `input` and `outputs` logs of Code Interpreter:274By listing the steps of a Run that called Code Interpreter, you can inspect the code `input` and `outputs` logs of Code Interpreter:

275 275 

276```javascript

277const runSteps = await openai.beta.threads.runs.steps.list(run.id, {

278 thread_id: thread.id,

279});

280```

281 

276```python282```python

277import os283import os

278 284 

285)291)

286```292```

287 293 

288```javascript

289const runSteps = await openai.beta.threads.runs.steps.list(run.id, {

290 thread_id: thread.id,

291});

292```

293 

294```bash294```bash

295curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \295curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \

296 -H "Authorization: Bearer $OPENAI_API_KEY" \296 -H "Authorization: Bearer $OPENAI_API_KEY" \

16 16 

17Create a new assistant with `file_search` enabled in the `tools` parameter of the Assistant.17Create a new assistant with `file_search` enabled in the `tools` parameter of the Assistant.

18 18 

19```python

20from openai import OpenAI

21 

22client = OpenAI()

23 

24assistant = client.beta.assistants.create(

25 name="Financial Analyst Assistant",

26 instructions="You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",

27 model="gpt-4o",

28 tools=[{"type": "file_search"}],

29)

30```

31 

32```javascript19```javascript

33import OpenAI from "openai";20import OpenAI from "openai";

34const openai = new OpenAI();21const openai = new OpenAI();

46main();33main();

47```34```

48 35 

36```python

37from openai import OpenAI

38 

39client = OpenAI()

40 

41assistant = client.beta.assistants.create(

42 name="Financial Analyst Assistant",

43 instructions="You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",

44 model="gpt-4o",

45 tools=[{"type": "file_search"}],

46)

47```

48 

49```bash49```bash

50curl https://api.openai.com/v1/assistants \50curl https://api.openai.com/v1/assistants \

51-H "Content-Type: application/json" \51-H "Content-Type: application/json" \

69Once the Vector Store is created, you should poll its status until all files are out of the `in_progress` state to69Once the Vector Store is created, you should poll its status until all files are out of the `in_progress` state to

70ensure that all content has finished processing. The SDK provides helpers to uploading and polling in one shot.70ensure that all content has finished processing. The SDK provides helpers to uploading and polling in one shot.

71 71 

72```javascript

73const fileStreams = [

74 fs.createReadStream("edgar/goog-10k.pdf"),

75 fs.createReadStream("edgar/brka-10k.txt"),

76];

77 

78// Create a vector store including our two files.

79let vectorStore = await openai.vectorStores.create({

80 name: "Financial Statement",

81});

82 

83await openai.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {

84 files: fileStreams,

85});

86```

87 

72```python88```python

73# Create a vector store called "Financial Statements"89# Create a vector store called "Financial Statements"

74vector_store = client.vector_stores.create(name="Financial Statements")90vector_store = client.vector_stores.create(name="Financial Statements")

92print(file_batch.file_counts)108print(file_batch.file_counts)

93```109```

94 110 

95```javascript

96const fileStreams = [

97 fs.createReadStream("edgar/goog-10k.pdf"),

98 fs.createReadStream("edgar/brka-10k.txt"),

99];

100 

101// Create a vector store including our two files.

102let vectorStore = await openai.vectorStores.create({

103 name: "Financial Statement",

104});

105 

106await openai.vectorStores.fileBatches.uploadAndPoll(vectorStore.id, {

107 files: fileStreams,

108});

109```

110 

111 111 

112### Step 3: Update the assistant to use the new Vector Store112### Step 3: Update the assistant to use the new Vector Store

113 113 

114To make the files accessible to your assistant, update the assistant’s `tool_resources` with the new `vector_store` id.114To make the files accessible to your assistant, update the assistant’s `tool_resources` with the new `vector_store` id.

115 115 

116```javascript

117await openai.beta.assistants.update(assistant.id, {

118 tool_resources: { file_search: { vector_store_ids: [vectorStore.id] } },

119});

120```

121 

116```python122```python

117assistant = client.beta.assistants.update(123assistant = client.beta.assistants.update(

118 assistant_id=assistant.id,124 assistant_id=assistant.id,

120)126)

121```127```

122 128 

123```javascript

124await openai.beta.assistants.update(assistant.id, {

125 tool_resources: { file_search: { vector_store_ids: [vectorStore.id] } },

126});

127```

128 

129 129 

130### Step 4: Create a thread130### Step 4: Create a thread

131 131 

133 133 

134In this example, the user attached a copy of Apple’s latest 10-K filing.134In this example, the user attached a copy of Apple’s latest 10-K filing.

135 135 

136```javascript

137// A user wants to attach a file to a specific message, let's upload it.

138const aapl10k = await openai.files.create({

139 file: fs.createReadStream("edgar/aapl-10k.pdf"),

140 purpose: "assistants",

141});

142 

143const thread = await openai.beta.threads.create({

144 messages: [

145 {

146 role: "user",

147 content:

148 "How many shares of AAPL were outstanding at the end of October 2023?",

149 // Attach the new file to the message.

150 attachments: [{ file_id: aapl10k.id, tools: [{ type: "file_search" }] }],

151 },

152 ],

153});

154 

155// The thread now has a vector store in its tool resources.

156console.log(thread.tool_resources?.file_search);

157```

158 

136```python159```python

137# Upload the user provided file to OpenAI160# Upload the user provided file to OpenAI

138message_file = client.files.create(161message_file = client.files.create(

158print(thread.tool_resources.file_search)181print(thread.tool_resources.file_search)

159```182```

160 183 

161```javascript

162// A user wants to attach a file to a specific message, let's upload it.

163const aapl10k = await openai.files.create({

164 file: fs.createReadStream("edgar/aapl-10k.pdf"),

165 purpose: "assistants",

166});

167 

168const thread = await openai.beta.threads.create({

169 messages: [

170 {

171 role: "user",

172 content:

173 "How many shares of AAPL were outstanding at the end of October 2023?",

174 // Attach the new file to the message.

175 attachments: [{ file_id: aapl10k.id, tools: [{ type: "file_search" }] }],

176 },

177 ],

178});

179 

180// The thread now has a vector store in its tool resources.

181console.log(thread.tool_resources?.file_search);

182```

183 

184 184 

185Vector stores created using message attachments have a default expiration policy of 7 days after they were last active (defined as the last time the vector store was part of a run). This default exists to help you manage your vector storage costs. You can override these expiration policies at any time. Learn more [here](#managing-costs-with-expiration-policies).185Vector stores created using message attachments have a default expiration policy of 7 days after they were last active (defined as the last time the vector store was part of a run). This default exists to help you manage your vector storage costs. You can override these expiration policies at any time. Learn more [here](#managing-costs-with-expiration-policies).

186 186 

192 192 

193With streaming193With streaming

194 194 

195```typescript

196const stream = openai.beta.threads.runs

197 .stream(thread.id, {

198 assistant_id: assistant.id,

199 })

200 .on("textCreated", () => console.log("assistant >"))

201 .on("toolCallCreated", (event) => console.log("assistant " + event.type))

202 .on("messageDone", async (event) => {

203 if (event.content[0].type === "text") {

204 const { text } = event.content[0];

205 const { annotations } = text;

206 const citations: string[] = [];

207 

208 let index = 0;

209 for (const annotation of annotations) {

210 text.value = text.value.replace(annotation.text, `[${index}]`);

211 if (annotation.type === "file_citation") {

212 const citedFile = await openai.files.retrieve(

213 annotation.file_citation.file_id

214 );

215 citations.push(`[${index}]${citedFile.filename}`);

216 }

217 index++;

218 }

219 

220 console.log(text.value);

221 console.log(citations.join("\n"));

222 }

223 });

224```

225 

195```python226```python

196from typing_extensions import override227from typing_extensions import override

197from openai import AssistantEventHandler, OpenAI228from openai import AssistantEventHandler, OpenAI

239 stream.until_done()270 stream.until_done()

240```271```

241 272 

273

274 

275

276 

277

278Without streaming

279 

242```typescript280```typescript

243const stream = openai.beta.threads.runs281const run = await openai.beta.threads.runs.createAndPoll(thread.id, {

244 .stream(thread.id, {

245 assistant_id: assistant.id,282 assistant_id: assistant.id,

246 })283});

247 .on("textCreated", () => console.log("assistant >"))284 

248 .on("toolCallCreated", (event) => console.log("assistant " + event.type))285const messages = await openai.beta.threads.messages.list(thread.id, {

249 .on("messageDone", async (event) => {286 run_id: run.id,

250 if (event.content[0].type === "text") {287});

251 const { text } = event.content[0];288 

289const message = messages.data.pop()!;

290if (message.content[0].type === "text") {

291 const { text } = message.content[0];

252 const { annotations } = text;292 const { annotations } = text;

253 const citations: string[] = [];293 const citations: string[] = [];

254 294 

266 306 

267 console.log(text.value);307 console.log(text.value);

268 console.log(citations.join("\n"));308 console.log(citations.join("\n"));

269 }309}

270 });

271```310```

272 311 

273

274 

275

276 

277

278Without streaming

279 

280```python312```python

281# Use the create and poll SDK helper to create a run and poll the status of313# Use the create and poll SDK helper to create a run and poll the status of

282# the run until it's in a terminal state.314# the run until it's in a terminal state.

305print("\n".join(citations))337print("\n".join(citations))

306```338```

307 339 

308```typescript

309const run = await openai.beta.threads.runs.createAndPoll(thread.id, {

310 assistant_id: assistant.id,

311});

312 

313const messages = await openai.beta.threads.messages.list(thread.id, {

314 run_id: run.id,

315});

316 

317const message = messages.data.pop()!;

318if (message.content[0].type === "text") {

319 const { text } = message.content[0];

320 const { annotations } = text;

321 const citations: string[] = [];

322 

323 let index = 0;

324 for (const annotation of annotations) {

325 text.value = text.value.replace(annotation.text, `[${index}]`);

326 if (annotation.type === "file_citation") {

327 const citedFile = await openai.files.retrieve(

328 annotation.file_citation.file_id

329 );

330 citations.push(`[${index}]${citedFile.filename}`);

331 }

332 index++;

333 }

334 

335 console.log(text.value);

336 console.log(citations.join("\n"));

337}

338```

339 

340 340 

341 341 

342Your new assistant will query both attached vector stores (one containing `goog-10k.pdf` and `brka-10k.txt`, and the other containing `aapl-10k.pdf`) and return this result from `aapl-10k.pdf`.342Your new assistant will query both attached vector stores (one containing `goog-10k.pdf` and `brka-10k.txt`, and the other containing `aapl-10k.pdf`) and return this result from `aapl-10k.pdf`.

380 380 

381You can create a vector store and add files to it in a single API call:381You can create a vector store and add files to it in a single API call:

382 382 

383```python383```javascript

384vector_store = client.vector_stores.create(384const vectorStore = await openai.vectorStores.create({

385 name="Product Documentation",385 name: "Product Documentation",

386 file_ids=[386 file_ids: [

387 "file_1",387 "file_1",

388 "file_2",388 "file_2",

389 "file_3",389 "file_3",

390 "file_4",390 "file_4",

391 "file_5",391 "file_5",

392 ],392 ],

393)393});

394```394```

395 395 

396```javascript396```python

397const vectorStore = await openai.vectorStores.create({397vector_store = client.vector_stores.create(

398 name: "Product Documentation",398 name="Product Documentation",

399 file_ids: [399 file_ids=[

400 "file_1",400 "file_1",

401 "file_2",401 "file_2",

402 "file_3",402 "file_3",

403 "file_4",403 "file_4",

404 "file_5",404 "file_5",

405 ],405 ],

406});406)

407```407```

408 408 

409 409 

413 413 

414Adding files is rate limited per vector store ID. Requests to `/vector_stores/{vector_store_id}/files` and `/vector_stores/{vector_store_id}/file_batches` share a per-vector-store limit of 300 requests per minute.414Adding files is rate limited per vector store ID. Requests to `/vector_stores/{vector_store_id}/files` and `/vector_stores/{vector_store_id}/file_batches` share a per-vector-store limit of 300 requests per minute.

415 415 

416```python

417file = client.vector_stores.files.create_and_poll(

418 vector_store_id="vs_abc123", file_id="file-abc123"

419)

420```

421 

422```javascript416```javascript

423const file = await openai.vectorStores.files.createAndPoll(417const file = await openai.vectorStores.files.createAndPoll(

424 "vs_abc123",418 "vs_abc123",

428);422);

429```423```

430 424 

425```python

426file = client.vector_stores.files.create_and_poll(

427 vector_store_id="vs_abc123", file_id="file-abc123"

428)

429```

430 

431 431 

432Alternatively, you can add several files to a vector store by [creating batches](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) of up to 500 files.432Alternatively, you can add several files to a vector store by [creating batches](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) of up to 500 files.

433 433 

435 435 

436For high-throughput ingestion into one vector store, prefer file batches whenever possible to reduce request volume and improve latency.436For high-throughput ingestion into one vector store, prefer file batches whenever possible to reduce request volume and improve latency.

437 437 

438```python

439batch = client.vector_stores.file_batches.create_and_poll(

440 vector_store_id="vs_abc123",

441 files=[

442 {"file_id": "file_1", "attributes": {"category": "finance"}},

443 {

444 "file_id": "file_2",

445 "chunking_strategy": {

446 "type": "static",

447 "max_chunk_size_tokens": 1000,

448 "chunk_overlap_tokens": 200,

449 },

450 },

451 ],

452)

453```

454 

455```javascript438```javascript

456const batch = await openai.vectorStores.fileBatches.createAndPoll(439const batch = await openai.vectorStores.fileBatches.createAndPoll(

457 "vs_abc123",440 "vs_abc123",

476);459);

477```460```

478 461 

462```python

463batch = client.vector_stores.file_batches.create_and_poll(

464 vector_store_id="vs_abc123",

465 files=[

466 {"file_id": "file_1", "attributes": {"category": "finance"}},

467 {

468 "file_id": "file_2",

469 "chunking_strategy": {

470 "type": "static",

471 "max_chunk_size_tokens": 1000,

472 "chunk_overlap_tokens": 200,

473 },

474 },

475 ],

476)

477```

478 

479 479 

480Similarly, these files can be removed from a vector store by either:480Similarly, these files can be removed from a vector store by either:

481 481 

490 490 

491You can attach vector stores to your Assistant or Thread using the `tool_resources` parameter.491You can attach vector stores to your Assistant or Thread using the `tool_resources` parameter.

492 492 

493```python

494assistant = client.beta.assistants.create(

495 instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",

496 model="gpt-4o",

497 tools=[{"type": "file_search"}],

498 tool_resources={"file_search": {"vector_store_ids": ["vs_1"]}},

499)

500 

501thread = client.beta.threads.create(

502 messages=[{"role": "user", "content": "How do I cancel my subscription?"}],

503 tool_resources={"file_search": {"vector_store_ids": ["vs_2"]}},

504)

505```

506 

507```javascript493```javascript

508const assistant = await openai.beta.assistants.create({494const assistant = await openai.beta.assistants.create({

509 instructions:495 instructions:

527});513});

528```514```

529 515 

516```python

517assistant = client.beta.assistants.create(

518 instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",

519 model="gpt-4o",

520 tools=[{"type": "file_search"}],

521 tool_resources={"file_search": {"vector_store_ids": ["vs_1"]}},

522)

523 

524thread = client.beta.threads.create(

525 messages=[{"role": "user", "content": "How do I cancel my subscription?"}],

526 tool_resources={"file_search": {"vector_store_ids": ["vs_2"]}},

527)

528```

529 

530 530 

531You can also attach a vector store to Threads or Assistants after they're created by updating them with the right `tool_resources`.531You can also attach a vector store to Threads or Assistants after they're created by updating them with the right `tool_resources`.

532 532 

571 571 

572Include file search results in response when creating a run572Include file search results in response when creating a run

573 573 

574```javascript

575import OpenAI from "openai";

576 

577const openai = new OpenAI();

578 

579const runStep = await openai.beta.threads.runs.steps.retrieve("step_abc123", {

580 thread_id: "thread_abc123",

581 run_id: "run_abc123",

582 include: ["step_details.tool_calls[*].file_search.results[*].content"],

583});

584 

585console.log(runStep);

586```

587 

574```python588```python

575from openai import OpenAI589from openai import OpenAI

576 590 

586print(run_step)600print(run_step)

587```601```

588 602 

589```javascript

590import OpenAI from "openai";

591 

592const openai = new OpenAI();

593 

594const runStep = await openai.beta.threads.runs.steps.retrieve("step_abc123", {

595 thread_id: "thread_abc123",

596 run_id: "run_abc123",

597 include: ["step_details.tool_calls[*].file_search.results[*].content"],

598});

599 

600console.log(runStep);

601```

602 

603```bash603```bash

604curl -g https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123?include[]=step_details.tool_calls[*].file_search.results[*].content \604curl -g https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123?include[]=step_details.tool_calls[*].file_search.results[*].content \

605-H "Authorization: Bearer $OPENAI_API_KEY" \605-H "Authorization: Bearer $OPENAI_API_KEY" \

631 631 

632In order to help you manage the costs associated with these `vector_store` objects, we have added support for expiration policies in the `vector_store` object. You can set these policies when creating or updating the `vector_store` object.632In order to help you manage the costs associated with these `vector_store` objects, we have added support for expiration policies in the `vector_store` object. You can set these policies when creating or updating the `vector_store` object.

633 633 

634```python

635vector_store = client.vector_stores.create(

636 name="Product Documentation",

637 file_ids=[

638 "file_1",

639 "file_2",

640 "file_3",

641 "file_4",

642 "file_5",

643 ],

644 expires_after={"anchor": "last_active_at", "days": 7},

645)

646```

647 

648```javascript634```javascript

649let vectorStore = await openai.vectorStores.create({635let vectorStore = await openai.vectorStores.create({

650 name: "rag-store",636 name: "rag-store",

662});648});

663```649```

664 650 

651```python

652vector_store = client.vector_stores.create(

653 name="Product Documentation",

654 file_ids=[

655 "file_1",

656 "file_2",

657 "file_3",

658 "file_4",

659 "file_5",

660 ],

661 expires_after={"anchor": "last_active_at", "days": 7},

662)

663```

664 

665 665 

666**Thread vector stores have default expiration policies**666**Thread vector stores have default expiration policies**

667 667 

669 669 

670When a vector store expires, runs on that thread will fail. To fix this, you can simply recreate a new `vector_store` with the same files and reattach it to the thread.670When a vector store expires, runs on that thread will fail. To fix this, you can simply recreate a new `vector_store` with the same files and reattach it to the thread.

671 671 

672```python

673all_files = list(client.vector_stores.files.list("vs_expired"))

674 

675vector_store = client.vector_stores.create(name="rag-store")

676client.beta.threads.update(

677 "thread_abc123",

678 tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},

679)

680 

681for file_batch in chunked(all_files, 100):

682 client.vector_stores.file_batches.create_and_poll(

683 vector_store_id=vector_store.id,

684 file_ids=[file.id for file in file_batch],

685 )

686```

687 

688```javascript672```javascript

689const fileIds = [];673const fileIds = [];

690for await (const file of openai.vectorStores.files.list(674for await (const file of openai.vectorStores.files.list(

707}691}

708```692```

709 693 

694```python

695all_files = list(client.vector_stores.files.list("vs_expired"))

696 

697vector_store = client.vector_stores.create(name="rag-store")

698client.beta.threads.update(

699 "thread_abc123",

700 tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},

701)

702 

703for file_batch in chunked(all_files, 100):

704 client.vector_stores.file_batches.create_and_poll(

705 vector_store_id=vector_store.id,

706 file_ids=[file.id for file in file_batch],

707 )

708```

709 

710 710 

711## Supported files711## Supported files

712 712 

20With the launch of Structured Outputs, you can now use the parameter `strict:20With the launch of Structured Outputs, you can now use the parameter `strict:

21 true` when using function calling with the Assistants API. For more21 true` when using function calling with the Assistants API. For more

22 information, refer to the [Function calling22 information, refer to the [Function calling

23 guide](https://developers.openai.com/api/docs/guides/function-calling#function-calling-with-structured-outputs).23 guide](https://developers.openai.com/api/docs/guides/function-calling#strict-mode). Please note that

24 Please note that Structured Outputs are not supported in the Assistants API24 Structured Outputs are not supported in the Assistants API when using vision.

25 when using vision.

26 25 

27### Step 1: Define functions26### Step 1: Define functions

28 27 

29When creating your assistant, you will first define the functions under the `tools` param of the assistant.28When creating your assistant, you will first define the functions under the `tools` param of the assistant.

30 29 

30```javascript

31const assistant = await client.beta.assistants.create({

32 model: "gpt-4o",

33 instructions:

34 "You are a weather bot. Use the provided functions to answer questions.",

35 tools: [

36 {

37 type: "function",

38 function: {

39 name: "getCurrentTemperature",

40 description: "Get the current temperature for a specific location",

41 parameters: {

42 type: "object",

43 properties: {

44 location: {

45 type: "string",

46 description: "The city and state, e.g., San Francisco, CA",

47 },

48 unit: {

49 type: "string",

50 enum: ["Celsius", "Fahrenheit"],

51 description:

52 "The temperature unit to use. Infer this from the user's location.",

53 },

54 },

55 required: ["location", "unit"],

56 },

57 },

58 },

59 {

60 type: "function",

61 function: {

62 name: "getRainProbability",

63 description: "Get the probability of rain for a specific location",

64 parameters: {

65 type: "object",

66 properties: {

67 location: {

68 type: "string",

69 description: "The city and state, e.g., San Francisco, CA",

70 },

71 },

72 required: ["location"],

73 },

74 },

75 },

76 ],

77});

78```

79 

31```python80```python

32from openai import OpenAI81from openai import OpenAI

33 82 

80)129)

81```130```

82 131 

83```javascript

84const assistant = await client.beta.assistants.create({

85 model: "gpt-4o",

86 instructions:

87 "You are a weather bot. Use the provided functions to answer questions.",

88 tools: [

89 {

90 type: "function",

91 function: {

92 name: "getCurrentTemperature",

93 description: "Get the current temperature for a specific location",

94 parameters: {

95 type: "object",

96 properties: {

97 location: {

98 type: "string",

99 description: "The city and state, e.g., San Francisco, CA",

100 },

101 unit: {

102 type: "string",

103 enum: ["Celsius", "Fahrenheit"],

104 description:

105 "The temperature unit to use. Infer this from the user's location.",

106 },

107 },

108 required: ["location", "unit"],

109 },

110 },

111 },

112 {

113 type: "function",

114 function: {

115 name: "getRainProbability",

116 description: "Get the probability of rain for a specific location",

117 parameters: {

118 type: "object",

119 properties: {

120 location: {

121 type: "string",

122 description: "The city and state, e.g., San Francisco, CA",

123 },

124 },

125 required: ["location"],

126 },

127 },

128 },

129 ],

130});

131```

132 

133 132 

134### Step 2: Create a Thread and add Messages133### Step 2: Create a Thread and add Messages

135 134 

136Create a Thread when a user starts a conversation and add Messages to the Thread as the user asks questions.135Create a Thread when a user starts a conversation and add Messages to the Thread as the user asks questions.

137 136 

138```python

139thread = client.beta.threads.create()

140message = client.beta.threads.messages.create(

141 thread_id=thread.id,

142 role="user",

143 content="What's the weather in San Francisco today and the likelihood it'll rain?",

144)

145```

146 

147```javascript137```javascript

148const thread = await client.beta.threads.create();138const thread = await client.beta.threads.create();

149const message = client.beta.threads.messages.create(thread.id, {139const message = client.beta.threads.messages.create(thread.id, {

153});143});

154```144```

155 145 

146```python

147thread = client.beta.threads.create()

148message = client.beta.threads.messages.create(

149 thread_id=thread.id,

150 role="user",

151 content="What's the weather in San Francisco today and the likelihood it'll rain?",

152)

153```

154 

156 155 

157### Step 3: Initiate a Run156### Step 3: Initiate a Run

158 157 

216 215 

217For the streaming case, we create an EventHandler class to handle events in the response stream and submit all tool outputs at once with the “submit tool outputs stream” helper in the Python and Node SDKs.216For the streaming case, we create an EventHandler class to handle events in the response stream and submit all tool outputs at once with the “submit tool outputs stream” helper in the Python and Node SDKs.

218 217 

219```python

220from typing_extensions import override

221from openai import AssistantEventHandler

222 

223class EventHandler(AssistantEventHandler):

224 @override

225 def on_event(self, event):

226 # Retrieve events that are denoted with 'requires_action'

227 # since these will have our tool_calls

228 if event.event == "thread.run.requires_action":

229 run_id = event.data.id # Retrieve the run ID from the event data

230 self.handle_requires_action(event.data, run_id)

231 

232 def handle_requires_action(self, data, run_id):

233 tool_outputs = []

234 

235 for tool in data.required_action.submit_tool_outputs.tool_calls:

236 if tool.function.name == "get_current_temperature":

237 tool_outputs.append({"tool_call_id": tool.id, "output": "57"})

238 elif tool.function.name == "get_rain_probability":

239 tool_outputs.append({"tool_call_id": tool.id, "output": "0.06"})

240 

241 # Submit all tool_outputs at the same time

242 self.submit_tool_outputs(tool_outputs, run_id)

243 

244 def submit_tool_outputs(self, tool_outputs, run_id):

245 # Use the submit_tool_outputs_stream helper

246 with client.beta.threads.runs.submit_tool_outputs_stream(

247 thread_id=self.current_run.thread_id,

248 run_id=self.current_run.id,

249 tool_outputs=tool_outputs,

250 event_handler=EventHandler(),

251 ) as stream:

252 for text in stream.text_deltas:

253 print(text, end="", flush=True)

254 print()

255 

256with client.beta.threads.runs.stream(

257 thread_id=thread.id,

258 assistant_id=assistant.id,

259 event_handler=EventHandler(),

260) as stream:

261 stream.until_done()

262```

263 

264```javascript218```javascript

265class EventHandler extends EventEmitter {219class EventHandler extends EventEmitter {

266 constructor(client) {220 constructor(client) {

336}290}

337```291```

338 292 

293```python

294from typing_extensions import override

295from openai import AssistantEventHandler

339 296 

297class EventHandler(AssistantEventHandler):

298 @override

299 def on_event(self, event):

300 # Retrieve events that are denoted with 'requires_action'

301 # since these will have our tool_calls

302 if event.event == "thread.run.requires_action":

303 run_id = event.data.id # Retrieve the run ID from the event data

304 self.handle_requires_action(event.data, run_id)

340 305 

306 def handle_requires_action(self, data, run_id):

307 tool_outputs = []

341 308 

309 for tool in data.required_action.submit_tool_outputs.tool_calls:

310 if tool.function.name == "get_current_temperature":

311 tool_outputs.append({"tool_call_id": tool.id, "output": "57"})

312 elif tool.function.name == "get_rain_probability":

313 tool_outputs.append({"tool_call_id": tool.id, "output": "0.06"})

342 314 

315 # Submit all tool_outputs at the same time

316 self.submit_tool_outputs(tool_outputs, run_id)

343 317 

318 def submit_tool_outputs(self, tool_outputs, run_id):

319 # Use the submit_tool_outputs_stream helper

320 with client.beta.threads.runs.submit_tool_outputs_stream(

321 thread_id=self.current_run.thread_id,

322 run_id=self.current_run.id,

323 tool_outputs=tool_outputs,

324 event_handler=EventHandler(),

325 ) as stream:

326 for text in stream.text_deltas:

327 print(text, end="", flush=True)

328 print()

344 329 

345Without streaming330with client.beta.threads.runs.stream(

331 thread_id=thread.id,

332 assistant_id=assistant.id,

333 event_handler=EventHandler(),

334) as stream:

335 stream.until_done()

336```

346 337 

347 338 

348 339

349Runs are asynchronous, which means you'll want to monitor their `status` by polling the Run object until a

350[terminal status](https://developers.openai.com/api/docs/assistants/deep-dive#runs-and-run-steps) is reached. For convenience, the 'create and poll' SDK helpers assist both in

351creating the run and then polling for its completion. Once the Run completes, you can list the

352Messages added to the Thread by the Assistant. Finally, you would retrieve all the `tool_outputs` from

353`required_action` and submit them at the same time to the 'submit tool outputs and poll' helper.

354 340 

355```python

356run = client.beta.threads.runs.create_and_poll(

357 thread_id=thread.id,

358 assistant_id=assistant.id,

359)

360 341

361if run.status == "completed":

362 messages = client.beta.threads.messages.list(thread_id=thread.id)

363 print(messages)

364 342 

365# Define the list to store tool outputs

366tool_outputs = []

367 343

368# Loop through each tool in the required action section344Without streaming

369if run.required_action:

370 for tool in run.required_action.submit_tool_outputs.tool_calls:

371 if tool.function.name == "get_current_temperature":

372 tool_outputs.append({"tool_call_id": tool.id, "output": "57"})

373 elif tool.function.name == "get_rain_probability":

374 tool_outputs.append({"tool_call_id": tool.id, "output": "0.06"})

375 345 

376# Submit all tool outputs at once after collecting them in a list

377if tool_outputs:

378 try:

379 run = client.beta.threads.runs.submit_tool_outputs_and_poll(

380 thread_id=thread.id,

381 run_id=run.id,

382 tool_outputs=tool_outputs,

383 )

384 print("Tool outputs submitted successfully.")

385 except Exception as e:

386 print("Failed to submit tool outputs:", e)

387else:

388 print("No tool outputs to submit.")

389 346

390if run.status == "completed":347 

391 messages = client.beta.threads.messages.list(thread_id=thread.id)348Runs are asynchronous, which means you'll want to monitor their `status` by polling the Run object until a

392 print(messages)349[terminal status](https://developers.openai.com/api/docs/assistants/deep-dive#runs-and-run-steps) is reached. For convenience, the 'create and poll' SDK helpers assist both in

393else:350creating the run and then polling for its completion. Once the Run completes, you can list the

394 print(run.status)351Messages added to the Thread by the Assistant. Finally, you would retrieve all the `tool_outputs` from

395```352`required_action` and submit them at the same time to the 'submit tool outputs and poll' helper.

396 353 

397```javascript354```javascript

398const handleRequiresAction = async (run) => {355const handleRequiresAction = async (run) => {

457handleRunStatus(run);414handleRunStatus(run);

458```415```

459 416 

417```python

418run = client.beta.threads.runs.create_and_poll(

419 thread_id=thread.id,

420 assistant_id=assistant.id,

421)

422 

423if run.status == "completed":

424 messages = client.beta.threads.messages.list(thread_id=thread.id)

425 print(messages)

426 

427# Define the list to store tool outputs

428tool_outputs = []

429 

430# Loop through each tool in the required action section

431if run.required_action:

432 for tool in run.required_action.submit_tool_outputs.tool_calls:

433 if tool.function.name == "get_current_temperature":

434 tool_outputs.append({"tool_call_id": tool.id, "output": "57"})

435 elif tool.function.name == "get_rain_probability":

436 tool_outputs.append({"tool_call_id": tool.id, "output": "0.06"})

437 

438# Submit all tool outputs at once after collecting them in a list

439if tool_outputs:

440 try:

441 run = client.beta.threads.runs.submit_tool_outputs_and_poll(

442 thread_id=thread.id,

443 run_id=run.id,

444 tool_outputs=tool_outputs,

445 )

446 print("Tool outputs submitted successfully.")

447 except Exception as e:

448 print("Failed to submit tool outputs:", e)

449else:

450 print("No tool outputs to submit.")

451 

452if run.status == "completed":

453 messages = client.beta.threads.messages.list(thread_id=thread.id)

454 print(messages)

455else:

456 print(run.status)

457```

458 

460 459 

461 460 

462### Using Structured Outputs461### Using Structured Outputs

463 462 

464When you enable [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) by supplying `strict: true`, the OpenAI API will pre-process your supplied schema on your first request, and then use this artifact to constrain the model to your schema.463When you enable [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) by supplying `strict: true`, the OpenAI API will pre-process your supplied schema on your first request, and then use this artifact to constrain the model to your schema.

465 464 

465```javascript

466const assistant = await client.beta.assistants.create({

467 model: "gpt-4o-2024-08-06",

468 instructions:

469 "You are a weather bot. Use the provided functions to answer questions.",

470 tools: [

471 {

472 type: "function",

473 function: {

474 name: "getCurrentTemperature",

475 description: "Get the current temperature for a specific location",

476 parameters: {

477 type: "object",

478 properties: {

479 location: {

480 type: "string",

481 description: "The city and state, e.g., San Francisco, CA",

482 },

483 unit: {

484 type: "string",

485 enum: ["Celsius", "Fahrenheit"],

486 description:

487 "The temperature unit to use. Infer this from the user's location.",

488 },

489 },

490 required: ["location", "unit"],

491 // highlight-start

492 additionalProperties: false,

493 // highlight-end

494 },

495 // highlight-start

496 strict: true,

497 // highlight-end

498 },

499 },

500 {

501 type: "function",

502 function: {

503 name: "getRainProbability",

504 description: "Get the probability of rain for a specific location",

505 parameters: {

506 type: "object",

507 properties: {

508 location: {

509 type: "string",

510 description: "The city and state, e.g., San Francisco, CA",

511 },

512 },

513 required: ["location"],

514 // highlight-start

515 additionalProperties: false,

516 // highlight-end

517 },

518 // highlight-start

519 strict: true,

520 // highlight-end

521 },

522 },

523 ],

524});

525```

526 

466```python527```python

467from openai import OpenAI528from openai import OpenAI

468 529 

526 ],587 ],

527)588)

528```589```

529 

530```javascript

531const assistant = await client.beta.assistants.create({

532 model: "gpt-4o-2024-08-06",

533 instructions:

534 "You are a weather bot. Use the provided functions to answer questions.",

535 tools: [

536 {

537 type: "function",

538 function: {

539 name: "getCurrentTemperature",

540 description: "Get the current temperature for a specific location",

541 parameters: {

542 type: "object",

543 properties: {

544 location: {

545 type: "string",

546 description: "The city and state, e.g., San Francisco, CA",

547 },

548 unit: {

549 type: "string",

550 enum: ["Celsius", "Fahrenheit"],

551 description:

552 "The temperature unit to use. Infer this from the user's location.",

553 },

554 },

555 required: ["location", "unit"],

556 // highlight-start

557 additionalProperties: false,

558 // highlight-end

559 },

560 // highlight-start

561 strict: true,

562 // highlight-end

563 },

564 },

565 {

566 type: "function",

567 function: {

568 name: "getRainProbability",

569 description: "Get the probability of rain for a specific location",

570 parameters: {

571 type: "object",

572 properties: {

573 location: {

574 type: "string",

575 description: "The city and state, e.g., San Francisco, CA",

576 },

577 },

578 required: ["location"],

579 // highlight-start

580 additionalProperties: false,

581 // highlight-end

582 },

583 // highlight-start

584 strict: true,

585 // highlight-end

586 },

587 },

588 ],

589});

590```

58}58}

59```59```

60 60 

61```ruby

62require "openai"

63 

64openai = OpenAI::Client.new(

65 admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")

66)

67```

68 

69```java61```java

70import com.openai.client.OpenAIClient;62import com.openai.client.OpenAIClient;

71import com.openai.client.okhttp.OpenAIOkHttpClient;63import com.openai.client.okhttp.OpenAIOkHttpClient;

74 OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();66 OpenAIOkHttpClient.builder().adminApiKey(System.getenv("OPENAI_ADMIN_KEY")).build();

75```67```

76 68 

69```ruby

70require "openai"

71 

72openai = OpenAI::Client.new(

73 admin_api_key: ENV.fetch("OPENAI_ADMIN_KEY")

74)

75```

76 

77 77 

78## Restrict model access for projects78## Restrict model access for projects

79 79 

119println(modelPermissions.Mode)119println(modelPermissions.Mode)

120```120```

121 121 

122```ruby

123model_permissions = openai.admin.organization.projects.model_permissions.update(

124 "proj_abc",

125 mode: :allow_list,

126 model_ids: ["gpt-4.1", "o3"]

127)

128 

129puts(model_permissions.mode)

130```

131 

132```java122```java

133import com.openai.models.admin.organization.projects.modelpermissions.ModelPermissionUpdateParams;123import com.openai.models.admin.organization.projects.modelpermissions.ModelPermissionUpdateParams;

134import com.openai.models.admin.organization.projects.modelpermissions.ProjectModelPermissions;124import com.openai.models.admin.organization.projects.modelpermissions.ProjectModelPermissions;

150System.out.println(modelPermissions.mode());140System.out.println(modelPermissions.mode());

151```141```

152 142 

143```ruby

144model_permissions = openai.admin.organization.projects.model_permissions.update(

145 "proj_abc",

146 mode: :allow_list,

147 model_ids: ["gpt-4.1", "o3"]

148)

149 

150puts(model_permissions.mode)

151```

152 

153 153 

154## Set an organization spend limit154## Set an organization spend limit

155 155 

232println(spendAlert.ID)232println(spendAlert.ID)

233```233```

234 234 

235```ruby

236spend_alert = openai.admin.organization.projects.spend_alerts.create(

237 "proj_abc",

238 currency: :USD,

239 interval: :month,

240 notification_channel: {

241 recipients: ["billing@example.com"],

242 type: :email,

243 subject_prefix: "[OpenAI spend]"

244 },

245 threshold_amount: 50_000

246)

247 

248puts(spend_alert.id)

249```

250 

251```java235```java

252import com.openai.models.admin.organization.projects.spendalerts.ProjectSpendAlert;236import com.openai.models.admin.organization.projects.spendalerts.ProjectSpendAlert;

253import com.openai.models.admin.organization.projects.spendalerts.SpendAlertCreateParams;237import com.openai.models.admin.organization.projects.spendalerts.SpendAlertCreateParams;

274System.out.println(spendAlert.id());258System.out.println(spendAlert.id());

275```259```

276 260 

261```ruby

262spend_alert = openai.admin.organization.projects.spend_alerts.create(

263 "proj_abc",

264 currency: :USD,

265 interval: :month,

266 notification_channel: {

267 recipients: ["billing@example.com"],

268 type: :email,

269 subject_prefix: "[OpenAI spend]"

270 },

271 threshold_amount: 50_000

272)

273 

274puts(spend_alert.id)

275```

276 

277 277 

278## Manage data retention278## Manage data retention

279 279 

316println(dataRetention.Type)316println(dataRetention.Type)

317```317```

318 318 

319```ruby

320data_retention = openai.admin.organization.projects.data_retention.update(

321 "proj_abc",

322 retention_type: :organization_default

323)

324 

325puts(data_retention.type)

326```

327 

328```java319```java

329import com.openai.models.admin.organization.projects.dataretention.DataRetentionUpdateParams;320import com.openai.models.admin.organization.projects.dataretention.DataRetentionUpdateParams;

330import com.openai.models.admin.organization.projects.dataretention.ProjectDataRetention;321import com.openai.models.admin.organization.projects.dataretention.ProjectDataRetention;

344System.out.println(dataRetention.type());335System.out.println(dataRetention.type());

345```336```

346 337 

338```ruby

339data_retention = openai.admin.organization.projects.data_retention.update(

340 "proj_abc",

341 retention_type: :organization_default

342)

343 

344puts(data_retention.type)

345```

346 

347 347 

348## Invite a user by email348## Invite a user by email

349 349 

383println(invite.ID)383println(invite.ID)

384```384```

385 385 

386```ruby

387invite = openai.admin.organization.invites.create(

388 email: "user@example.com",

389 role: :reader

390)