resources/beta/subresources/assistants/methods/retrieve/index.md +0 −310 deleted
File Deleted View Diff
1## Retrieve assistant
2
3**get** `/assistants/{assistant_id}`
4
5Retrieves an assistant.
6
7### Path Parameters
8
9- `assistant_id: string`
10
11### Returns
12
13- `Assistant object { id, created_at, description, 10 more }`
14
15 Represents an `assistant` that can call the model and use tools.
16
17 - `id: string`
18
19 The identifier, which can be referenced in API endpoints.
20
21 - `created_at: number`
22
23 The Unix timestamp (in seconds) for when the assistant was created.
24
25 - `description: string or null`
26
27 The description of the assistant. The maximum length is 512 characters.
28
29 - `instructions: string or null`
30
31 The system instructions that the assistant uses. The maximum length is 256,000 characters.
32
33 - `metadata: Metadata or null`
34
35 Set of 16 key-value pairs that can be attached to an object. This can be
36 useful for storing additional information about the object in a structured
37 format, and querying for objects via API or the dashboard.
38
39 Keys are strings with a maximum length of 64 characters. Values are strings
40 with a maximum length of 512 characters.
41
42 - `model: string`
43
44 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.
45
46 - `name: string or null`
47
48 The name of the assistant. The maximum length is 256 characters.
49
50 - `object: "assistant"`
51
52 The object type, which is always `assistant`.
53
54 - `"assistant"`
55
56 - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool`
57
58 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`.
59
60 - `CodeInterpreterTool object { type }`
61
62 - `type: "code_interpreter"`
63
64 The type of tool being defined: `code_interpreter`
65
66 - `"code_interpreter"`
67
68 - `FileSearchTool object { type, file_search }`
69
70 - `type: "file_search"`
71
72 The type of tool being defined: `file_search`
73
74 - `"file_search"`
75
76 - `file_search: optional object { max_num_results, ranking_options }`
77
78 Overrides for the file search tool.
79
80 - `max_num_results: optional number`
81
82 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.
83
84 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.
85
86 - `ranking_options: optional object { score_threshold, ranker }`
87
88 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.
89
90 See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.
91
92 - `score_threshold: number`
93
94 The score threshold for the file search. All values must be a floating point number between 0 and 1.
95
96 - `ranker: optional "auto" or "default_2024_08_21"`
97
98 The ranker to use for the file search. If not specified will use the `auto` ranker.
99
100 - `"auto"`
101
102 - `"default_2024_08_21"`
103
104 - `FunctionTool object { function, type }`
105
106 - `function: FunctionDefinition`
107
108 - `name: string`
109
110 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.
111
112 - `description: optional string`
113
114 A description of what the function does, used by the model to choose when and how to call the function.
115
116 - `parameters: optional FunctionParameters`
117
118 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.
119
120 Omitting `parameters` defines a function with an empty parameter list.
121
122 - `strict: optional boolean or null`
123
124 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).
125
126 - `type: "function"`
127
128 The type of tool being defined: `function`
129
130 - `"function"`
131
132 - `response_format: optional AssistantResponseFormatOption or null`
133
134 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`.
135
136 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).
137
138 Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
139
140 **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.
141
142 - `"auto"`
143
144 `auto` is the default value
145
146 - `"auto"`
147
148 - `ResponseFormatText object { type }`
149
150 Default response format. Used to generate text responses.
151
152 - `type: "text"`
153
154 The type of response format being defined. Always `text`.
155
156 - `"text"`
157
158 - `ResponseFormatJSONObject object { type }`
159
160 JSON object response format. An older method of generating JSON responses.
161 Using `json_schema` is recommended for models that support it. Note that the
162 model will not generate JSON without a system or user message instructing it
163 to do so.
164
165 - `type: "json_object"`
166
167 The type of response format being defined. Always `json_object`.
168
169 - `"json_object"`
170
171 - `ResponseFormatJSONSchema object { json_schema, type }`
172
173 JSON Schema response format. Used to generate structured JSON responses.
174 Learn more about [Structured Outputs](/docs/guides/structured-outputs).
175
176 - `json_schema: object { name, description, schema, strict }`
177
178 Structured Outputs configuration options, including a JSON Schema.
179
180 - `name: string`
181
182 The name of the response format. Must be a-z, A-Z, 0-9, or contain
183 underscores and dashes, with a maximum length of 64.
184
185 - `description: optional string`
186
187 A description of what the response format is for, used by the model to
188 determine how to respond in the format.
189
190 - `schema: optional map[unknown]`
191
192 The schema for the response format, described as a JSON Schema object.
193 Learn how to build JSON schemas [here](https://json-schema.org/).
194
195 - `strict: optional boolean or null`
196
197 Whether to enable strict schema adherence when generating the output.
198 If set to true, the model will always follow the exact schema defined
199 in the `schema` field. Only a subset of JSON Schema is supported when
200 `strict` is `true`. To learn more, read the [Structured Outputs
201 guide](/docs/guides/structured-outputs).
202
203 - `type: "json_schema"`
204
205 The type of response format being defined. Always `json_schema`.
206
207 - `"json_schema"`
208
209 - `temperature: optional number or null`
210
211 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.
212
213 - `tool_resources: optional object { code_interpreter, file_search } or null`
214
215 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.
216
217 - `code_interpreter: optional object { file_ids }`
218
219 - `file_ids: optional array of string`
220
221 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.
222
223 - `file_search: optional object { vector_store_ids }`
224
225 - `vector_store_ids: optional array of string`
226
227 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.
228
229 - `top_p: optional number or null`
230
231 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.
232
233 We generally recommend altering this or temperature but not both.
234
235### Example
236
237```http
238curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \
239 -H 'OpenAI-Beta: assistants=v2' \
240 -H "Authorization: Bearer $OPENAI_API_KEY"
241```
242
243#### Response
244
245```json
246{
247 "id": "id",
248 "created_at": 0,
249 "description": "description",
250 "instructions": "instructions",
251 "metadata": {
252 "foo": "string"
253 },
254 "model": "model",
255 "name": "name",
256 "object": "assistant",
257 "tools": [
258 {
259 "type": "code_interpreter"
260 }
261 ],
262 "response_format": "auto",
263 "temperature": 1,
264 "tool_resources": {
265 "code_interpreter": {
266 "file_ids": [
267 "string"
268 ]
269 },
270 "file_search": {
271 "vector_store_ids": [
272 "string"
273 ]
274 }
275 },
276 "top_p": 1
277}
278```
279
280### Example
281
282```http
283curl https://api.openai.com/v1/assistants/asst_abc123 \
284 -H "Content-Type: application/json" \
285 -H "Authorization: Bearer $OPENAI_API_KEY" \
286 -H "OpenAI-Beta: assistants=v2"
287```
288
289#### Response
290
291```json
292{
293 "id": "asst_abc123",
294 "object": "assistant",
295 "created_at": 1699009709,
296 "name": "HR Helper",
297 "description": null,
298 "model": "gpt-4o",
299 "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
300 "tools": [
301 {
302 "type": "file_search"
303 }
304 ],
305 "metadata": {},
306 "top_p": 1.0,
307 "temperature": 1.0,
308 "response_format": "auto"
309}
310```