Reference 2026-09-10 18:01 UTC to 2026-09-11 20:00 UTC

1## Create project service account API key1## Create an API key for a service account

2 2 

3**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys`3**post** `/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys`

4 4 

1## Retrieve project spend limit1## Get project spend limit

2 2 

3**get** `/organization/projects/{project_id}/spend_limit`3**get** `/organization/projects/{project_id}/spend_limit`

4 4 

1## Retrieve organization spend limit1## Get organization spend limit

2 2 

3**get** `/organization/spend_limit`3**get** `/organization/spend_limit`

4 4 

2 2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5<a id="transcript.text.segment"></a>

6 

5## transcript.text.segment7## transcript.text.segment

6 8 

7Emitted when a diarized transcription returns a completed segment with speaker information. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with `stream` set to `true` and `response_format` set to `diarized_json`.9Emitted when a diarized transcription returns a completed segment with speaker information. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with `stream` set to `true` and `response_format` set to `diarized_json`.

10 12 

11Schema name: `TranscriptTextSegmentEvent`13Schema name: `TranscriptTextSegmentEvent`

12 14 

13```json15- `id: string`

14{16 

15 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema)": {17 Unique identifier for the segment.

16 "kind": "HttpDeclTypeAlias",18 

17 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent",19- `end: number`

18 "docstring": "Emitted when a diarized transcription returns a completed segment with speaker information. Only emitted when you [create a transcription](/api/reference/resources/audio/subresources/transcriptions/methods/create) with `stream` set to `true` and `response_format` set to `diarized_json`.\n",20 

19 "ident": "TranscriptionTextSegmentEvent",21 End timestamp of the segment in seconds.

20 "type": {22 

21 "kind": "HttpTypeObject",23- `speaker: string`

22 "members": [24 

23 {25 Speaker label for this segment.

24 "ident": "id"26 

25 },27- `start: number`

26 {28 

27 "ident": "end"29 Start timestamp of the segment in seconds.

28 },30 

29 {31- `text: string`

30 "ident": "speaker"32 

31 },33 Transcript text for this segment.

32 {34 

33 "ident": "start"35- `type: "transcript.text.segment"`

34 },36 

35 {37 The type of the event. Always `transcript.text.segment`.

36 "ident": "text"38 

37 },39 - `"transcript.text.segment"`

38 {

39 "ident": "type"

40 }

41 ]

42 },

43 "childrenParentSchema": "object",

44 "children": [

45 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) id",

46 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) end",

47 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) speaker",

48 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) start",

49 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) text",

50 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) type"

51 ]

52 },

53 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) id": {

54 "kind": "HttpDeclProperty",

55 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/id",

56 "deprecated": false,

57 "key": "id",

58 "docstring": "Unique identifier for the segment.",

59 "type": {

60 "kind": "HttpTypeString"

61 },

62 "optional": false,

63 "nullable": false,

64 "schemaType": "string",

65 "children": []

66 },

67 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) end": {

68 "kind": "HttpDeclProperty",

69 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/end",

70 "deprecated": false,

71 "key": "end",

72 "docstring": "End timestamp of the segment in seconds.",

73 "type": {

74 "kind": "HttpTypeNumber"

75 },

76 "constraints": {

77 "format": "double"

78 },

79 "optional": false,

80 "nullable": false,

81 "schemaType": "number",

82 "children": []

83 },

84 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) speaker": {

85 "kind": "HttpDeclProperty",

86 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/speaker",

87 "deprecated": false,

88 "key": "speaker",

89 "docstring": "Speaker label for this segment.",

90 "type": {

91 "kind": "HttpTypeString"

92 },

93 "optional": false,

94 "nullable": false,

95 "schemaType": "string",

96 "children": []

97 },

98 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) start": {

99 "kind": "HttpDeclProperty",

100 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/start",

101 "deprecated": false,

102 "key": "start",

103 "docstring": "Start timestamp of the segment in seconds.",

104 "type": {

105 "kind": "HttpTypeNumber"

106 },

107 "constraints": {

108 "format": "double"

109 },

110 "optional": false,

111 "nullable": false,

112 "schemaType": "number",

113 "children": []

114 },

115 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) text": {

116 "kind": "HttpDeclProperty",

117 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/text",

118 "deprecated": false,

119 "key": "text",

120 "docstring": "Transcript text for this segment.",

121 "type": {

122 "kind": "HttpTypeString"

123 },

124 "optional": false,

125 "nullable": false,

126 "schemaType": "string",

127 "children": []

128 },

129 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) type": {

130 "kind": "HttpDeclProperty",

131 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/type",

132 "deprecated": false,

133 "key": "type",

134 "docstring": "The type of the event. Always `transcript.text.segment`.",

135 "type": {

136 "kind": "HttpTypeUnion",

137 "oasRef": "#/components/schemas/TranscriptTextSegmentEvent/properties/type",

138 "types": [

139 {

140 "kind": "HttpTypeLiteral",

141 "literal": "transcript.text.segment"

142 }

143 ]

144 },

145 "optional": false,

146 "nullable": false,

147 "schemaType": "enum",

148 "childrenParentSchema": "enum",

149 "children": [

150 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) type > (member) 0"

151 ]

152 },

153 "(resource) audio.transcriptions > (model) transcription_text_segment_event > (schema) > (property) type > (member) 0": {

154 "kind": "HttpDeclReference",

155 "type": {

156 "kind": "HttpTypeLiteral",

157 "literal": "transcript.text.segment"

158 }

159 }

160}

161```

162 40 

163### Example41### Example

164 42 

173}51}

174```52```

175 53 

54<a id="transcript.text.delta"></a>

55 

176## transcript.text.delta56## transcript.text.delta

177 57 

178Emitted when there is an additional text delta. This is also the first event emitted when the transcription starts. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.58Emitted when there is an additional text delta. This is also the first event emitted when the transcription starts. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.

181 61 

182Schema name: `TranscriptTextDeltaEvent`62Schema name: `TranscriptTextDeltaEvent`

183 63 

184```json64- `delta: string`

185{65 

186 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema)": {66 The text delta that was additionally transcribed.

187 "kind": "HttpDeclTypeAlias",67 

188 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent",68- `type: "transcript.text.delta"`

189 "docstring": "Emitted when there is an additional text delta. This is also the first event emitted when the transcription starts. Only emitted when you [create a transcription](/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.",69 

190 "ident": "TranscriptionTextDeltaEvent",70 The type of the event. Always `transcript.text.delta`.

191 "type": {71 

192 "kind": "HttpTypeObject",72 - `"transcript.text.delta"`

193 "members": [73 

194 {74- `logprobs: optional array of object { token, bytes, logprob }`

195 "ident": "delta"75 

196 },76 The log probabilities of the delta. Only included if you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `include[]` parameter set to `logprobs`.

197 {77 

198 "ident": "type"78 - `token: optional string`

199 },79 

200 {80 The token that was used to generate the log probability.

201 "ident": "logprobs"81 

202 },82 - `bytes: optional array of number`

203 {83 

204 "ident": "segment_id"84 The bytes that were used to generate the log probability.

205 }85 

206 ]86 - `logprob: optional number`

207 },87 

208 "childrenParentSchema": "object",88 The log probability of the token.

209 "children": [89 

210 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) delta",90- `segment_id: optional string`

211 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) type",91 

212 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs",92 Identifier of the diarized segment that this delta belongs to. Only present when using `gpt-4o-transcribe-diarize`.

213 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) segment_id"

214 ]

215 },

216 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) delta": {

217 "kind": "HttpDeclProperty",

218 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/delta",

219 "deprecated": false,

220 "key": "delta",

221 "docstring": "The text delta that was additionally transcribed.\n",

222 "type": {

223 "kind": "HttpTypeString"

224 },

225 "optional": false,

226 "nullable": false,

227 "schemaType": "string",

228 "children": []

229 },

230 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) type": {

231 "kind": "HttpDeclProperty",

232 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/type",

233 "deprecated": false,

234 "key": "type",

235 "docstring": "The type of the event. Always `transcript.text.delta`.\n",

236 "type": {

237 "kind": "HttpTypeUnion",

238 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/type",

239 "types": [

240 {

241 "kind": "HttpTypeLiteral",

242 "literal": "transcript.text.delta"

243 }

244 ]

245 },

246 "optional": false,

247 "nullable": false,

248 "schemaType": "enum",

249 "childrenParentSchema": "enum",

250 "children": [

251 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) type > (member) 0"

252 ]

253 },

254 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs": {

255 "kind": "HttpDeclProperty",

256 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs",

257 "deprecated": false,

258 "key": "logprobs",

259 "docstring": "The log probabilities of the delta. Only included if you [create a transcription](/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `include[]` parameter set to `logprobs`.\n",

260 "type": {

261 "kind": "HttpTypeArray",

262 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs",

263 "elementType": {

264 "kind": "HttpTypeObject",

265 "members": [

266 {

267 "ident": "token"

268 },

269 {

270 "ident": "bytes"

271 },

272 {

273 "ident": "logprob"

274 }

275 ]

276 }

277 },

278 "optional": true,

279 "nullable": false,

280 "schemaType": "array",

281 "childrenParentSchema": "object",

282 "children": [

283 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) token",

284 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) bytes",

285 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) logprob"

286 ]

287 },

288 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) segment_id": {

289 "kind": "HttpDeclProperty",

290 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/segment_id",

291 "deprecated": false,

292 "key": "segment_id",

293 "docstring": "Identifier of the diarized segment that this delta belongs to. Only present when using `gpt-4o-transcribe-diarize`.\n",

294 "type": {

295 "kind": "HttpTypeString"

296 },

297 "optional": true,

298 "nullable": false,

299 "schemaType": "string",

300 "children": []

301 },

302 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) type > (member) 0": {

303 "kind": "HttpDeclReference",

304 "type": {

305 "kind": "HttpTypeLiteral",

306 "literal": "transcript.text.delta"

307 }

308 },

309 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) token": {

310 "kind": "HttpDeclProperty",

311 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs/items/properties/token",

312 "deprecated": false,

313 "key": "token",

314 "docstring": "The token that was used to generate the log probability.\n",

315 "type": {

316 "kind": "HttpTypeString"

317 },

318 "optional": true,

319 "nullable": false,

320 "schemaType": "string",

321 "children": []

322 },

323 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) bytes": {

324 "kind": "HttpDeclProperty",

325 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs/items/properties/bytes",

326 "deprecated": false,

327 "key": "bytes",

328 "docstring": "The bytes that were used to generate the log probability.\n",

329 "type": {

330 "kind": "HttpTypeArray",

331 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs/items/properties/bytes",

332 "elementType": {

333 "kind": "HttpTypeNumber"

334 }

335 },

336 "optional": true,

337 "nullable": false,

338 "schemaType": "array",

339 "children": []

340 },

341 "(resource) audio.transcriptions > (model) transcription_text_delta_event > (schema) > (property) logprobs > (items) > (property) logprob": {

342 "kind": "HttpDeclProperty",

343 "oasRef": "#/components/schemas/TranscriptTextDeltaEvent/properties/logprobs/items/properties/logprob",

344 "deprecated": false,

345 "key": "logprob",

346 "docstring": "The log probability of the token.\n",

347 "type": {

348 "kind": "HttpTypeNumber"

349 },

350 "optional": true,

351 "nullable": false,

352 "schemaType": "number",

353 "children": []

354 }

355}

356```

357 93 

358### Example94### Example

359 95 

364}100}

365```101```

366 102 

103<a id="transcript.text.done"></a>

104 

367## transcript.text.done105## transcript.text.done

368 106 

369Emitted when the transcription is complete. Contains the complete transcription text. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.107Emitted when the transcription is complete. Contains the complete transcription text. Only emitted when you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.

372 110 

373Schema name: `TranscriptTextDoneEvent`111Schema name: `TranscriptTextDoneEvent`

374 112 

375```json113- `text: string`

376{114 

377 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema)": {115 The text that was transcribed.

378 "kind": "HttpDeclTypeAlias",116 

379 "oasRef": "#/components/schemas/TranscriptTextDoneEvent",117- `type: "transcript.text.done"`

380 "docstring": "Emitted when the transcription is complete. Contains the complete transcription text. Only emitted when you [create a transcription](/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `Stream` parameter set to `true`.",118 

381 "ident": "TranscriptionTextDoneEvent",119 The type of the event. Always `transcript.text.done`.

382 "type": {120 

383 "kind": "HttpTypeObject",121 - `"transcript.text.done"`

384 "members": [122 

385 {123- `languages: optional array of TranscriptionLanguage`

386 "ident": "text"124 

387 },125 The languages detected in the audio. Returned by `gpt-transcribe`. An empty array indicates that no language could be reliably detected.

388 {126 

389 "ident": "type"127 - `code: string`

390 },128 

391 {129 The code of a language detected in the audio.

392 "ident": "languages"130 

393 },131- `logprobs: optional array of object { token, bytes, logprob }`

394 {132 

395 "ident": "logprobs"133 The log probabilities of the individual tokens in the transcription. Only included if you [create a transcription](https://developers.openai.com/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `include[]` parameter set to `logprobs`.

396 },134 

397 {135 - `token: optional string`

398 "ident": "usage"136 

399 }137 The token that was used to generate the log probability.

400 ]138 

401 },139 - `bytes: optional array of number`

402 "childrenParentSchema": "object",140 

403 "children": [141 The bytes that were used to generate the log probability.

404 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) text",142 

405 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) type",143 - `logprob: optional number`

406 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) languages",144 

407 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs",145 The log probability of the token.

408 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage"146 

409 ]147- `usage: optional object { input_tokens, output_tokens, total_tokens, 2 more }`

410 },148 

411 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) text": {149 Usage statistics for models billed by token usage.

412 "kind": "HttpDeclProperty",150 

413 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/text",151 - `input_tokens: number`

414 "deprecated": false,152 

415 "key": "text",153 Number of input tokens billed for this request.

416 "docstring": "The text that was transcribed.\n",154 

417 "type": {155 - `output_tokens: number`

418 "kind": "HttpTypeString"156 

419 },157 Number of output tokens generated.

420 "optional": false,158 

421 "nullable": false,159 - `total_tokens: number`

422 "schemaType": "string",160 

423 "children": []161 Total number of tokens used (input + output).

424 },162 

425 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) type": {163 - `type: "tokens"`

426 "kind": "HttpDeclProperty",164 

427 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/type",165 The type of the usage object. Always `tokens` for this variant.

428 "deprecated": false,166 

429 "key": "type",167 - `"tokens"`

430 "docstring": "The type of the event. Always `transcript.text.done`.\n",168 

431 "type": {169 - `input_token_details: optional object { audio_tokens, text_tokens }`

432 "kind": "HttpTypeUnion",170 

433 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/type",171 Details about the input tokens billed for this request.

434 "types": [172 

435 {173 - `audio_tokens: optional number`

436 "kind": "HttpTypeLiteral",174 

437 "literal": "transcript.text.done"175 Number of audio tokens billed for this request.

438 }176 

439 ]177 - `text_tokens: optional number`

440 },178 

441 "optional": false,179 Number of text tokens billed for this request.

442 "nullable": false,

443 "schemaType": "enum",

444 "childrenParentSchema": "enum",

445 "children": [

446 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) type > (member) 0"

447 ]

448 },

449 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) languages": {

450 "kind": "HttpDeclProperty",

451 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/languages",

452 "deprecated": false,

453 "key": "languages",

454 "docstring": "The languages detected in the audio. Returned by `gpt-transcribe`. An empty array indicates that no language could be reliably detected.\n",

455 "type": {

456 "kind": "HttpTypeArray",

457 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/languages",

458 "elementType": {

459 "kind": "HttpTypeReference",

460 "ident": "TranscriptionLanguage",

461 "$ref": "(resource) audio.transcriptions > (model) transcription_language > (schema)"

462 }

463 },

464 "optional": true,

465 "nullable": false,

466 "schemaType": "array",

467 "childrenParentSchema": "object",

468 "children": [

469 "(resource) audio.transcriptions > (model) transcription_language > (schema) > (property) code"

470 ]

471 },

472 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs": {

473 "kind": "HttpDeclProperty",

474 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs",

475 "deprecated": false,

476 "key": "logprobs",

477 "docstring": "The log probabilities of the individual tokens in the transcription. Only included if you [create a transcription](/api/reference/resources/audio/subresources/transcriptions/methods/create) with the `include[]` parameter set to `logprobs`.\n",

478 "type": {

479 "kind": "HttpTypeArray",

480 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs",

481 "elementType": {

482 "kind": "HttpTypeObject",

483 "members": [

484 {

485 "ident": "token"

486 },

487 {

488 "ident": "bytes"

489 },

490 {

491 "ident": "logprob"

492 }

493 ]

494 }

495 },

496 "optional": true,

497 "nullable": false,

498 "schemaType": "array",

499 "childrenParentSchema": "object",

500 "children": [

501 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) token",

502 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) bytes",

503 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) logprob"

504 ]

505 },

506 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage": {

507 "kind": "HttpDeclProperty",

508 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/usage",

509 "deprecated": false,

510 "key": "usage",

511 "docstring": "Usage statistics for models billed by token usage.",

512 "title": "Token Usage",

513 "type": {

514 "kind": "HttpTypeObject",

515 "members": [

516 {

517 "ident": "input_tokens"

518 },

519 {

520 "ident": "output_tokens"

521 },

522 {

523 "ident": "total_tokens"

524 },

525 {

526 "ident": "type"

527 },

528 {

529 "ident": "input_token_details"

530 }

531 ]

532 },

533 "optional": true,

534 "nullable": false,

535 "schemaType": "object",

536 "childrenParentSchema": "object",

537 "children": [

538 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_tokens",

539 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) output_tokens",

540 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) total_tokens",

541 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) type",

542 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details"

543 ]

544 },

545 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) type > (member) 0": {

546 "kind": "HttpDeclReference",

547 "type": {

548 "kind": "HttpTypeLiteral",

549 "literal": "transcript.text.done"

550 }

551 },

552 "(resource) audio.transcriptions > (model) transcription_language > (schema) > (property) code": {

553 "kind": "HttpDeclProperty",

554 "oasRef": "#/components/schemas/TranscriptionLanguage/properties/code",

555 "deprecated": false,

556 "key": "code",

557 "docstring": "The code of a language detected in the audio.",

558 "type": {

559 "kind": "HttpTypeString"

560 },

561 "optional": false,

562 "nullable": false,

563 "schemaType": "string",

564 "children": []

565 },

566 "(resource) audio.transcriptions > (model) transcription_language > (schema)": {

567 "kind": "HttpDeclTypeAlias",

568 "oasRef": "#/components/schemas/TranscriptionLanguage",

569 "docstring": "A language detected in transcribed audio.",

570 "ident": "TranscriptionLanguage",

571 "type": {

572 "kind": "HttpTypeObject",

573 "members": [

574 {

575 "ident": "code"

576 }

577 ]

578 },

579 "childrenParentSchema": "object",

580 "children": [

581 "(resource) audio.transcriptions > (model) transcription_language > (schema) > (property) code"

582 ]

583 },

584 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) token": {

585 "kind": "HttpDeclProperty",

586 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs/items/properties/token",

587 "deprecated": false,

588 "key": "token",

589 "docstring": "The token that was used to generate the log probability.\n",

590 "type": {

591 "kind": "HttpTypeString"

592 },

593 "optional": true,

594 "nullable": false,

595 "schemaType": "string",

596 "children": []

597 },

598 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) bytes": {

599 "kind": "HttpDeclProperty",

600 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs/items/properties/bytes",

601 "deprecated": false,

602 "key": "bytes",

603 "docstring": "The bytes that were used to generate the log probability.\n",

604 "type": {

605 "kind": "HttpTypeArray",

606 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs/items/properties/bytes",

607 "elementType": {

608 "kind": "HttpTypeNumber"

609 }

610 },

611 "optional": true,

612 "nullable": false,

613 "schemaType": "array",

614 "children": []

615 },

616 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) logprobs > (items) > (property) logprob": {

617 "kind": "HttpDeclProperty",

618 "oasRef": "#/components/schemas/TranscriptTextDoneEvent/properties/logprobs/items/properties/logprob",

619 "deprecated": false,

620 "key": "logprob",

621 "docstring": "The log probability of the token.\n",

622 "type": {

623 "kind": "HttpTypeNumber"

624 },

625 "optional": true,

626 "nullable": false,

627 "schemaType": "number",

628 "children": []

629 },

630 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_tokens": {

631 "kind": "HttpDeclProperty",

632 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/input_tokens",

633 "deprecated": false,

634 "key": "input_tokens",

635 "docstring": "Number of input tokens billed for this request.",

636 "type": {

637 "kind": "HttpTypeNumber"

638 },

639 "optional": false,

640 "nullable": false,

641 "schemaType": "integer",

642 "children": []

643 },

644 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) output_tokens": {

645 "kind": "HttpDeclProperty",

646 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/output_tokens",

647 "deprecated": false,

648 "key": "output_tokens",

649 "docstring": "Number of output tokens generated.",

650 "type": {

651 "kind": "HttpTypeNumber"

652 },

653 "optional": false,

654 "nullable": false,

655 "schemaType": "integer",

656 "children": []

657 },

658 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) total_tokens": {

659 "kind": "HttpDeclProperty",

660 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/total_tokens",

661 "deprecated": false,

662 "key": "total_tokens",

663 "docstring": "Total number of tokens used (input + output).",

664 "type": {

665 "kind": "HttpTypeNumber"

666 },

667 "optional": false,

668 "nullable": false,

669 "schemaType": "integer",

670 "children": []

671 },

672 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) type": {

673 "kind": "HttpDeclProperty",

674 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/type",

675 "deprecated": false,

676 "key": "type",

677 "docstring": "The type of the usage object. Always `tokens` for this variant.",

678 "type": {

679 "kind": "HttpTypeUnion",

680 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/type",

681 "types": [

682 {

683 "kind": "HttpTypeLiteral",

684 "literal": "tokens"

685 }

686 ]

687 },

688 "optional": false,

689 "nullable": false,

690 "schemaType": "enum",

691 "childrenParentSchema": "enum",

692 "children": [

693 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) type > (member) 0"

694 ]

695 },

696 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details": {

697 "kind": "HttpDeclProperty",

698 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/input_token_details",

699 "deprecated": false,

700 "key": "input_token_details",

701 "docstring": "Details about the input tokens billed for this request.",

702 "type": {

703 "kind": "HttpTypeObject",

704 "members": [

705 {

706 "ident": "audio_tokens"

707 },

708 {

709 "ident": "text_tokens"

710 }

711 ]

712 },

713 "optional": true,

714 "nullable": false,

715 "schemaType": "object",

716 "childrenParentSchema": "object",

717 "children": [

718 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details > (property) audio_tokens",

719 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details > (property) text_tokens"

720 ]

721 },

722 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) type > (member) 0": {

723 "kind": "HttpDeclReference",

724 "type": {

725 "kind": "HttpTypeLiteral",

726 "literal": "tokens"

727 }

728 },

729 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details > (property) audio_tokens": {

730 "kind": "HttpDeclProperty",

731 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/input_token_details/properties/audio_tokens",

732 "deprecated": false,

733 "key": "audio_tokens",

734 "docstring": "Number of audio tokens billed for this request.",

735 "type": {

736 "kind": "HttpTypeNumber"

737 },

738 "optional": true,

739 "nullable": false,

740 "schemaType": "integer",

741 "children": []

742 },

743 "(resource) audio.transcriptions > (model) transcription_text_done_event > (schema) > (property) usage > (property) input_token_details > (property) text_tokens": {

744 "kind": "HttpDeclProperty",

745 "oasRef": "#/components/schemas/TranscriptTextUsageTokens/properties/input_token_details/properties/text_tokens",

746 "deprecated": false,

747 "key": "text_tokens",

748 "docstring": "Number of text tokens billed for this request.",

749 "type": {

750 "kind": "HttpTypeNumber"

751 },

752 "optional": true,

753 "nullable": false,

754 "schemaType": "integer",

755 "children": []

756 }

757}

758```

759 180 

760### Example181### Example

761 182 

1## Create an agent

2 

3**post** `/agents`

4 

5Creates a reusable agent without storing credentials. See [agent configuration](/api/docs/guides/agents-api/configuration).

6 

7### Body Parameters

8 

9- `model: string`

10 

11 The model to use for the agent. The requested model name is preserved.

12 

13- `instructions: optional string or null`

14 

15 Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions.

16 

17- `metadata: optional map[string] or null`

18 

19 Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map.

20 

21- `multi_agent: optional MultiAgentConfigParam or null`

22 

23 Explicit configuration for creating and coordinating subagents.

24 

25 - `enabled: boolean`

26 

27 Whether subagent tools are enabled.

28 

29 - `max_concurrent_subagents: optional number`

30 

31 Maximum number of subagents that may run concurrently. Defaults to 6.

32 

33- `name: optional string or null`

34 

35 A human-readable name for the agent. Omission or null leaves the agent unnamed.

36 

37- `reasoning: optional AgentReasoningParam or null`

38 

39 Reasoning configuration for the agent.

40 

41 - `effort: optional "none" or "minimal" or "low" or 4 more or null`

42 

43 The amount of reasoning effort the model should use.

44 

45 - `"none"`

46 

47 - `"minimal"`

48 

49 - `"low"`

50 

51 - `"medium"`

52 

53 - `"high"`

54 

55 - `"xhigh"`

56 

57 - `"max"`

58 

59 - `summary: optional "concise" or "detailed" or "auto" or null`

60 

61 The reasoning summary format requested from the model.

62 

63 - `"concise"`

64 

65 Returns a concise reasoning summary when supported.

66 

67 - `"detailed"`

68 

69 Returns a detailed reasoning summary when supported.

70 

71 - `"auto"`

72 

73 Automatically selects the most detailed summary supported by the model.

74 

75- `service_tier: optional "auto" or "default" or "flex" or 2 more or null`

76 

77 The service tier used for model requests.

78 

79 - `"auto"`

80 

81 Selects the service tier automatically.

82 

83 - `"default"`

84 

85 Uses the default service tier.

86 

87 - `"flex"`

88 

89 Uses the flex service tier.

90 

91 - `"priority"`

92 

93 Uses the priority service tier.

94 

95 - `"fast"`

96 

97 Uses the fast service tier.

98 

99- `text: optional AgentTextParam or null`

100 

101 Configuration for text generated by the agent.

102 

103 - `format: optional TextFormatParam or null`

104 

105 The output format for generated text.

106 

107 - `Text object { type }`

108 

109 Generates ordinary text without a structured-output constraint.

110 

111 - `type: "text"`

112 

113 The type of the object. Always `text`.

114 

115 - `"text"`

116 

117 - `JSONSchema object { schema, type }`

118 

119 Constrains generated text to a JSON Schema.

120 

121 - `schema: map[unknown]`

122 

123 The JSON Schema that generated text must match.

124 

125 - `type: "json_schema"`

126 

127 The type of the object. Always `json_schema`.

128 

129 - `"json_schema"`

130 

131 - `verbosity: optional "low" or "medium" or "high" or null`

132 

133 The amount of text the model should produce.

134 

135 - `"low"`

136 

137 Produces less text.

138 

139 - `"medium"`

140 

141 Uses the default amount of text.

142 

143 - `"high"`

144 

145 Produces more text.

146 

147- `tools: optional array of PersistedAgentToolParam or null`

148 

149 Tools available to the agent. Defaults to an empty list.

150 

151 - `Function object { description, name, parameters, 2 more }`

152 

153 A function defined by the application.

154 

155 - `description: string`

156 

157 A description of what the function does.

158 

159 - `name: string`

160 

161 The name of the function.

162 

163 - `parameters: map[unknown]`

164 

165 A JSON Schema object describing the function's arguments.

166 

167 - `type: "function"`

168 

169 The type of the object. Always `function`.

170 

171 - `"function"`

172 

173 - `defer_loading: optional boolean`

174 

175 Whether this function is deferred and discovered through tool search. Defaults to `false`.

176 

177 - `ToolSearch object { type }`

178 

179 Discovers deferred function tools and loads them into the model context.

180 

181 - `type: "tool_search"`

182 

183 The type of the object. Always `tool_search`.

184 

185 - `"tool_search"`

186 

187 - `ProgrammaticToolCalling object { type, enabled }`

188 

189 Enables calling tools from model-generated code.

190 

191 - `type: "programmatic_tool_calling"`

192 

193 The type of the object. Always `programmatic_tool_calling`.

194 

195 - `"programmatic_tool_calling"`

196 

197 - `enabled: optional boolean`

198 

199 Whether tools can be called from model-generated code. Defaults to `true`.

200 

201 - `Mcp object { server_label, transport, type, 5 more }`

202 

203 Tools provided by a remote MCP server without stored credentials.

204 

205 - `server_label: string`

206 

207 A label used to identify the MCP server in tool calls.

208 

209 - `transport: PersistedMcpTransportParam`

210 

211 The credential-free transport used to connect to the MCP server.

212 

213 - `HTTP object { server_url, type, headers }`

214 

215 Connects to an MCP server over HTTP.

216 

217 - `server_url: string`

218 

219 The URL of the MCP server.

220 

221 - `type: "http"`

222 

223 The type of the object. Always `http`.

224 

225 - `"http"`

226 

227 - `headers: optional map[string] or null`

228 

229 Non-secret HTTP headers sent to the MCP server.

230 

231 - `Stdio object { command, cwd, type, 2 more }`

232 

233 Starts an MCP server as a local process.

234 

235 - `command: string`

236 

237 The command used to start the MCP server.

238 

239 - `cwd: string`

240 

241 The working directory used to start the MCP server.

242 

243 - `type: "stdio"`

244 

245 The type of the object. Always `stdio`.

246 

247 - `"stdio"`

248 

249 - `args: optional array of string or null`

250 

251 Arguments passed to the MCP server command.

252 

253 - `env_vars: optional array of string or null`

254 

255 Environment variable names to inherit from the selected execution environment.

256 

257 - `type: "mcp"`

258 

259 The type of the object. Always `mcp`.

260 

261 - `"mcp"`

262 

263 - `allowed_tools: optional array of string or null`

264 

265 The MCP tools the agent may call. All server tools are allowed when omitted.

266 

267 - `connection_origin: optional "service" or "environment" or null`

268 

269 Where outbound MCP HTTP connections originate.

270 

271 - `"service"`

272 

273 Uses the Managed Agents service network.

274 

275 - `"environment"`

276 

277 Uses the session's execution environment.

278 

279 - `credential_id: optional string or null`

280 

281 The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL.

282 

283 - `request_metadata: optional map[unknown] or null`

284 

285 Metadata included with requests to this MCP server.

286 

287 - `required: optional boolean`

288 

289 Whether this MCP server must initialize before the first turn. Defaults to `false`.

290 

291 - `WebSearch object { type, allowed_domains, context_size, 2 more }`

292 

293 Web search.

294 

295 - `type: "web_search"`

296 

297 The type of the object. Always `web_search`.

298 

299 - `"web_search"`

300 

301 - `allowed_domains: optional array of string or null`

302 

303 Domains the search may include.

304 

305 - `context_size: optional "low" or "medium" or "high" or null`

306 

307 The amount of web search context made available to the model.

308 

309 - `"low"`

310 

311 - `"medium"`

312 

313 - `"high"`

314 

315 - `location: optional object { city, country, region, timezone } or null`

316 

317 Approximate user location used to localize web search results.

318 

319 - `city: optional string or null`

320 

321 The city name.

322 

323 - `country: optional string or null`

324 

325 The two-letter ISO country code, such as `US`.

326 

327 - `region: optional string or null`

328 

329 The region or state name.

330 

331 - `timezone: optional string or null`

332 

333 The IANA timezone, such as `America/Los_Angeles`.

334 

335 - `mode: optional "disabled" or "cached" or "live" or null`

336 

337 The source used for web search results.

338 

339 - `"disabled"`

340 

341 Disables web search.

342 

343 - `"cached"`

344 

345 Uses cached search results.

346 

347 - `"live"`

348 

349 Searches the live web.

350 

351### Returns

352 

353- `Agent object { id, created_at, instructions, 10 more }`

354 

355 A reusable agent scoped to the caller's project.

356 

357 - `id: string`

358 

359 The ID of the reusable agent.

360 

361 - `created_at: number`

362 

363 The Unix timestamp, in seconds, when the agent was created.

364 

365 - `instructions: string or null`

366 

367 Custom instructions appended to the agent's default base instructions.

368 

369 - `metadata: map[string]`

370 

371 Custom string key-value pairs attached to the agent.

372 

373 - `model: string`

374 

375 The requested model name used for inference.

376 

377 - `multi_agent: MultiAgentConfig`

378 

379 The resolved configuration for creating and coordinating subagents.

380 

381 - `enabled: boolean`

382 

383 Whether subagent tools are enabled. Defaults to false.

384 

385 - `max_concurrent_subagents: number or null`

386 

387 Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

388 

389 - `name: string or null`

390 

391 A human-readable name for the agent, or null if it is unnamed.

392 

393 - `object: "agent"`

394 

395 The object type. Always `agent`.

396 

397 - `"agent"`

398 

399 - `reasoning: AgentReasoning`

400 

401 The resolved reasoning configuration, including the model default for an omitted effort.

402 

403 - `effort: "none" or "minimal" or "low" or 4 more or null`

404 

405 The amount of reasoning effort used by an agent.

406 

407 - `"none"`

408 

409 - `"minimal"`

410 

411 - `"low"`

412 

413 - `"medium"`

414 

415 - `"high"`

416 

417 - `"xhigh"`

418 

419 - `"max"`

420 

421 - `summary: "concise" or "detailed" or "auto" or null`

422 

423 The reasoning summary format requested from an agent.

424 

425 - `"concise"`

426 

427 Returns a concise reasoning summary when supported.

428 

429 - `"detailed"`

430 

431 Returns a detailed reasoning summary when supported.

432 

433 - `"auto"`

434 

435 Automatically selects the most detailed summary supported by the model.

436 

437 - `service_tier: "auto" or "default" or "flex" or 2 more`

438 

439 The resolved service-tier policy used for model requests.

440 

441 - `"auto"`

442 

443 - `"default"`

444 

445 - `"flex"`

446 

447 - `"priority"`

448 

449 - `"fast"`

450 

451 - `text: AgentText`

452 

453 The resolved configuration for text generated by the agent.

454 

455 - `format: TextFormat`

456 

457 The effective output format. Defaults to ordinary text.

458 

459 - `Text object { type }`

460 

461 Generates ordinary text without a structured-output constraint.

462 

463 - `type: "text"`

464 

465 The type of the object. Always `text`.

466 

467 - `"text"`

468 

469 - `JSONSchema object { schema, type }`

470 

471 Constrains generated text to a JSON Schema.

472 

473 - `schema: map[unknown]`

474 

475 The JSON Schema that generated text must match.

476 

477 - `type: "json_schema"`

478 

479 The type of the object. Always `json_schema`.

480 

481 - `"json_schema"`

482 

483 - `verbosity: "low" or "medium" or "high"`

484 

485 The amount of text produced by the agent. Defaults to `medium`.

486 

487 - `"low"`

488 

489 - `"medium"`

490 

491 - `"high"`

492 

493 - `tools: array of PersistedAgentTool`

494 

495 Tools available to the agent.

496 

497 - `Function object { defer_loading, description, name, 2 more }`

498 

499 A function defined by the application.

500 

501 - `defer_loading: boolean`

502 

503 Whether the function is deferred and discovered through tool search.

504 

505 - `description: string`

506 

507 A description of what the function does.

508 

509 - `name: string`

510 

511 The name of the function.

512 

513 - `parameters: map[unknown]`

514 

515 A JSON Schema object describing the function's arguments.

516 

517 - `type: "function"`

518 

519 The type of the object. Always `function`.

520 

521 - `"function"`

522 

523 - `ToolSearch object { type }`

524 

525 Discovers deferred function tools and loads them into the model context.

526 

527 - `type: "tool_search"`

528 

529 The type of the object. Always `tool_search`.

530 

531 - `"tool_search"`

532 

533 - `ProgrammaticToolCalling object { enabled, type }`

534 

535 Enables calling tools from model-generated code.

536 

537 - `enabled: boolean`

538 

539 Whether tools can be called from model-generated code.

540 

541 - `type: "programmatic_tool_calling"`

542 

543 The type of the object. Always `programmatic_tool_calling`.

544 

545 - `"programmatic_tool_calling"`

546 

547 - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }`

548 

549 Tools provided by a remote MCP server without stored credentials.

550 

551 - `allowed_tools: array of string or null`

552 

553 The MCP tools the agent may call, or null when all server tools are allowed.

554 

555 - `connection_origin: "service" or "environment"`

556 

557 Where outbound MCP HTTP connections originate.

558 

559 - `"service"`

560 

561 - `"environment"`

562 

563 - `credential_id: string or null`

564 

565 The vault credential selected for this MCP server, if any.

566 

567 - `request_metadata: map[unknown]`

568 

569 Metadata included with requests to this MCP server.

570 

571 - `required: boolean`

572 

573 Whether this MCP server must initialize before the first turn.

574 

575 - `server_label: string`

576 

577 A label used to identify the MCP server in tool calls.

578 

579 - `transport: PersistedMcpTransport`

580 

581 The credential-free transport used to connect to the MCP server.

582 

583 - `HTTP object { headers, server_url, type }`

584 

585 Connects to an MCP server over HTTP.

586 

587 - `headers: map[string]`

588 

589 Non-secret HTTP headers sent to the MCP server.

590 

591 - `server_url: string`

592 

593 The URL of the MCP server.

594 

595 - `type: "http"`

596 

597 The type of the object. Always `http`.

598 

599 - `"http"`

600 

601 - `Stdio object { args, command, cwd, 2 more }`

602 

603 Starts an MCP server as a local process.

604 

605 - `args: array of string`

606 

607 Arguments passed to the MCP server command.

608 

609 - `command: string`

610 

611 The command used to start the MCP server.

612 

613 - `cwd: string`

614 

615 The working directory used to start the MCP server.

616 

617 - `env_vars: array of string`

618 

619 Environment variable names inherited from the execution environment.

620 

621 - `type: "stdio"`

622 

623 The type of the object. Always `stdio`.

624 

625 - `"stdio"`

626 

627 - `type: "mcp"`

628 

629 The type of the object. Always `mcp`.

630 

631 - `"mcp"`

632 

633 - `WebSearch object { allowed_domains, context_size, location, 2 more }`

634 

635 Web search.

636 

637 - `allowed_domains: array of string or null`

638 

639 Allowed search domains, or `null` when the search is unrestricted.

640 

641 - `context_size: "low" or "medium" or "high"`

642 

643 The amount of search context made available to the model. Defaults to `medium`.

644 

645 - `"low"`

646 

647 - `"medium"`

648 

649 - `"high"`

650 

651 - `location: object { city, country, region, timezone } or null`

652 

653 Approximate user location used to localize web search results.

654 

655 - `city: string or null`

656 

657 The city name.

658 

659 - `country: string or null`

660 

661 The two-letter ISO country code, such as `US`.

662 

663 - `region: string or null`

664 

665 The region or state name.

666 

667 - `timezone: string or null`

668 

669 The IANA timezone, such as `America/Los_Angeles`.

670 

671 - `mode: "disabled" or "cached" or "live"`

672 

673 The source used for web search results.

674 

675 - `"disabled"`

676 

677 - `"cached"`

678 

679 - `"live"`

680 

681 - `type: "web_search"`

682 

683 The type of the object. Always `web_search`.

684 

685 - `"web_search"`

686 

687 - `updated_at: number`

688 

689 The Unix timestamp, in seconds, when the agent was last updated.

690 

691### Example

692 

693```http

694curl https://api.openai.com/v1/agents \

695 -H 'Content-Type: application/json' \

696 -H 'OpenAI-Beta: agents=v1' \

697 -H "Authorization: Bearer $OPENAI_API_KEY" \

698 -d '{

699 "model": "model"

700 }'

701```

702 

703#### Response

704 

705```json

706{

707 "id": "id",

708 "created_at": 0,

709 "instructions": "instructions",

710 "metadata": {

711 "foo": "string"

712 },

713 "model": "model",

714 "multi_agent": {

715 "enabled": true,

716 "max_concurrent_subagents": 1

717 },

718 "name": "name",

719 "object": "agent",

720 "reasoning": {

721 "effort": "none",

722 "summary": "concise"

723 },

724 "service_tier": "auto",

725 "text": {

726 "format": {

727 "type": "text"

728 },

729 "verbosity": "low"

730 },

731 "tools": [

732 {

733 "defer_loading": true,

734 "description": "description",

735 "name": "name",

736 "parameters": {

737 "foo": "bar"

738 },

739 "type": "function"

740 }

741 ],

742 "updated_at": 0

743}

744```

1## Delete an agent

2 

3**delete** `/agents/{agent_id}`

4 

5Deletes a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration).

6 

7### Path Parameters

8 

9- `agent_id: string`

10 

11### Returns

12 

13- `AgentDeleted object { id, deleted, object }`

14 

15 A deleted reusable agent.

16 

17 - `id: string`

18 

19 The ID of the deleted agent.

20 

21 - `deleted: boolean`

22 

23 Whether the agent was deleted. Always `true`.

24 

25 - `object: "agent.deleted"`

26 

27 The object type. Always `agent.deleted`.

28 

29 - `"agent.deleted"`

30 

31### Example

32 

33```http

34curl https://api.openai.com/v1/agents/$AGENT_ID \

35 -X DELETE \

36 -H 'OpenAI-Beta: agents=v1' \

37 -H "Authorization: Bearer $OPENAI_API_KEY"

38```

39 

40#### Response

41 

42```json

43{

44 "id": "id",

45 "deleted": true,

46 "object": "agent.deleted"

47}

48```

1## List agents

2 

3**get** `/agents`

4 

5Lists reusable agents in the current project. See [agent configuration](/api/docs/guides/agents-api/configuration).

6 

7### Query Parameters

8 

9- `after: optional string`

10 

11 Return resources after this resource ID in the selected order.

12 

13- `limit: optional number or null`

14 

15 The maximum number of resources to return.

16 

17- `order: optional "asc" or "desc"`

18 

19 The order in which resources are returned. Defaults to `desc`.

20 

21 - `"asc"`

22 

23 Returns resources in ascending order.

24 

25 - `"desc"`

26 

27 Returns resources in descending order.

28 

29### Returns

30 

31- `data: array of Agent`

32 

33 The resources returned in this page, in the requested sort order.

34 

35 - `id: string`

36 

37 The ID of the reusable agent.

38 

39 - `created_at: number`

40 

41 The Unix timestamp, in seconds, when the agent was created.

42 

43 - `instructions: string or null`

44 

45 Custom instructions appended to the agent's default base instructions.

46 

47 - `metadata: map[string]`

48 

49 Custom string key-value pairs attached to the agent.

50 

51 - `model: string`

52 

53 The requested model name used for inference.

54 

55 - `multi_agent: MultiAgentConfig`

56 

57 The resolved configuration for creating and coordinating subagents.

58 

59 - `enabled: boolean`

60 

61 Whether subagent tools are enabled. Defaults to false.

62 

63 - `max_concurrent_subagents: number or null`

64 

65 Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

66 

67 - `name: string or null`

68 

69 A human-readable name for the agent, or null if it is unnamed.

70 

71 - `object: "agent"`

72 

73 The object type. Always `agent`.

74 

75 - `"agent"`

76 

77 - `reasoning: AgentReasoning`

78 

79 The resolved reasoning configuration, including the model default for an omitted effort.

80 

81 - `effort: "none" or "minimal" or "low" or 4 more or null`

82 

83 The amount of reasoning effort used by an agent.

84 

85 - `"none"`

86 

87 - `"minimal"`

88 

89 - `"low"`

90 

91 - `"medium"`

92 

93 - `"high"`

94 

95 - `"xhigh"`

96 

97 - `"max"`

98 

99 - `summary: "concise" or "detailed" or "auto" or null`

100 

101 The reasoning summary format requested from an agent.

102 

103 - `"concise"`

104 

105 Returns a concise reasoning summary when supported.

106 

107 - `"detailed"`

108 

109 Returns a detailed reasoning summary when supported.

110 

111 - `"auto"`

112 

113 Automatically selects the most detailed summary supported by the model.

114 

115 - `service_tier: "auto" or "default" or "flex" or 2 more`

116 

117 The resolved service-tier policy used for model requests.

118 

119 - `"auto"`

120 

121 - `"default"`

122 

123 - `"flex"`

124 

125 - `"priority"`

126 

127 - `"fast"`

128 

129 - `text: AgentText`

130 

131 The resolved configuration for text generated by the agent.

132 

133 - `format: TextFormat`

134 

135 The effective output format. Defaults to ordinary text.

136 

137 - `Text object { type }`

138 

139 Generates ordinary text without a structured-output constraint.

140 

141 - `type: "text"`

142 

143 The type of the object. Always `text`.

144 

145 - `"text"`

146 

147 - `JSONSchema object { schema, type }`

148 

149 Constrains generated text to a JSON Schema.

150 

151 - `schema: map[unknown]`

152 

153 The JSON Schema that generated text must match.

154 

155 - `type: "json_schema"`

156 

157 The type of the object. Always `json_schema`.

158 

159 - `"json_schema"`

160 

161 - `verbosity: "low" or "medium" or "high"`

162 

163 The amount of text produced by the agent. Defaults to `medium`.

164 

165 - `"low"`

166 

167 - `"medium"`

168 

169 - `"high"`

170 

171 - `tools: array of PersistedAgentTool`

172 

173 Tools available to the agent.

174 

175 - `Function object { defer_loading, description, name, 2 more }`

176 

177 A function defined by the application.

178 

179 - `defer_loading: boolean`

180 

181 Whether the function is deferred and discovered through tool search.

182 

183 - `description: string`

184 

185 A description of what the function does.

186 

187 - `name: string`

188 

189 The name of the function.

190 

191 - `parameters: map[unknown]`

192 

193 A JSON Schema object describing the function's arguments.

194 

195 - `type: "function"`

196 

197 The type of the object. Always `function`.

198 

199 - `"function"`

200 

201 - `ToolSearch object { type }`

202 

203 Discovers deferred function tools and loads them into the model context.

204 

205 - `type: "tool_search"`

206 

207 The type of the object. Always `tool_search`.

208 

209 - `"tool_search"`

210 

211 - `ProgrammaticToolCalling object { enabled, type }`

212 

213 Enables calling tools from model-generated code.

214 

215 - `enabled: boolean`

216 

217 Whether tools can be called from model-generated code.

218 

219 - `type: "programmatic_tool_calling"`

220 

221 The type of the object. Always `programmatic_tool_calling`.

222 

223 - `"programmatic_tool_calling"`

224 

225 - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }`

226 

227 Tools provided by a remote MCP server without stored credentials.