Files

Create container file

post /containers/{container_id}/files

Create a Container File

You can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID.

Path Parameters

container_id: string

Body Parameters

file: optional string

The File object (not file name) to be uploaded.
file_id: optional string

Name of the file to create.

Returns

id: string

Unique identifier for the file.
bytes: number

Size of the file in bytes.
container_id: string

The container this file belongs to.
created_at: number

Unix timestamp (in seconds) when the file was created.
object: string

The type of this object (container.file).
path: string

Path of the file in the container.
source: string

Source of the file (e.g., user, assistant).

Example

curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

Response

{
  "id": "id",
  "bytes": 0,
  "container_id": "container_id",
  "created_at": 0,
  "object": "object",
  "path": "path",
  "source": "source"
}

Example

curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file="@example.txt"

Response

{
  "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",
  "object": "container.file",
  "created_at": 1747848842,
  "bytes": 880,
  "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",
  "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",
  "source": "user"
}

Delete a container file

delete /containers/{container_id}/files/{file_id}

Delete Container File

Path Parameters

container_id: string
file_id: string

Example

curl https://api.openai.com/v1/containers/$CONTAINER_ID/files/$FILE_ID \
    -X DELETE \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Example

curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
    "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",
    "object": "container.file.deleted",
    "deleted": true
}

List container files

get /containers/{container_id}/files

List Container files

Path Parameters

container_id: string

Query Parameters

after: optional string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: optional number

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order: optional "asc" or "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
- "asc"
- "desc"

Returns

data: array of object { id, bytes, container_id, 4 more }

A list of container files.
- id: string
  
  Unique identifier for the file.
- bytes: number
  
  Size of the file in bytes.
- container_id: string
  
  The container this file belongs to.
- created_at: number
  
  Unix timestamp (in seconds) when the file was created.
- object: string
  
  The type of this object (container.file).
- path: string
  
  Path of the file in the container.
- source: string
  
  Source of the file (e.g., user, assistant).
first_id: string

The ID of the first file in the list.
has_more: boolean

Whether there are more files available.
last_id: string

The ID of the last file in the list.
object: "list"

The type of object returned, must be 'list'.
- "list"

Example

curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "id",
      "bytes": 0,
      "container_id": "container_id",
      "created_at": 0,
      "object": "object",
      "path": "path",
      "source": "source"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

Example

curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
    "object": "list",
    "data": [
        {
            "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",
            "object": "container.file",
            "created_at": 1747848842,
            "bytes": 880,
            "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",
            "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",
            "source": "user"
        }
    ],
    "first_id": "cfile_682e0e8a43c88191a7978f477a09bdf5",
    "has_more": false,
    "last_id": "cfile_682e0e8a43c88191a7978f477a09bdf5"
}

Retrieve container file

get /containers/{container_id}/files/{file_id}

Retrieve Container File

Path Parameters

container_id: string
file_id: string

Returns

id: string

Unique identifier for the file.
bytes: number

Size of the file in bytes.
container_id: string

The container this file belongs to.
created_at: number

Unix timestamp (in seconds) when the file was created.
object: string

The type of this object (container.file).
path: string

Path of the file in the container.
source: string

Source of the file (e.g., user, assistant).

Example

curl https://api.openai.com/v1/containers/$CONTAINER_ID/files/$FILE_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "bytes": 0,
  "container_id": "container_id",
  "created_at": 0,
  "object": "object",
  "path": "path",
  "source": "source"
}

Example

curl https://api.openai.com/v1/containers/container_123/files/file_456 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
    "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",
    "object": "container.file",
    "created_at": 1747848842,
    "bytes": 880,
    "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",
    "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",
    "source": "user"
}

Domain Types

File Create Response

FileCreateResponse object { id, bytes, container_id, 4 more }
- id: string
  
  Unique identifier for the file.
- bytes: number
  
  Size of the file in bytes.
- container_id: string
  
  The container this file belongs to.
- created_at: number
  
  Unix timestamp (in seconds) when the file was created.
- object: string
  
  The type of this object (container.file).
- path: string
  
  Path of the file in the container.
- source: string
  
  Source of the file (e.g., user, assistant).

File List Response

FileListResponse object { id, bytes, container_id, 4 more }
- id: string
  
  Unique identifier for the file.
- bytes: number
  
  Size of the file in bytes.
- container_id: string
  
  The container this file belongs to.
- created_at: number
  
  Unix timestamp (in seconds) when the file was created.
- object: string
  
  The type of this object (container.file).
- path: string
  
  Path of the file in the container.
- source: string
  
  Source of the file (e.g., user, assistant).

File Retrieve Response

FileRetrieveResponse object { id, bytes, container_id, 4 more }
- id: string
  
  Unique identifier for the file.
- bytes: number
  
  Size of the file in bytes.
- container_id: string
  
  The container this file belongs to.
- created_at: number
  
  Unix timestamp (in seconds) when the file was created.
- object: string
  
  The type of this object (container.file).
- path: string
  
  Path of the file in the container.
- source: string
  
  Source of the file (e.g., user, assistant).

Content

Retrieve container file content

get /containers/{container_id}/files/{file_id}/content

Retrieve Container File Content

Path Parameters

container_id: string
file_id: string

Example

curl https://api.openai.com/v1/containers/$CONTAINER_ID/files/$FILE_ID/content \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Example

curl https://api.openai.com/v1/containers/container_123/files/cfile_456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Response

<binary content of the file>

resources/containers/subresources/files/index.md +124 −123

1# Files1# Files

2 2

~~3## List container files~~3## Create container file

4 4

~~5**get** `/containers/{container_id}/files`~~5**post** `/containers/{container_id}/files`

6 6

~~7List Container files~~7Create a Container File

9You can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID.

8 10

9### Path Parameters11### Path Parameters

10 12

11- `container_id: string`13- `container_id: string`

12 14

~~13### Query Parameters~~15### Body Parameters

~~15- `after: optional string`~~

17 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

~~19- `limit: optional number`~~

~~21 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.~~

22 16

~~23- `order: optional "asc" or "desc"`~~17- `file: optional string`

24 18

~~25 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.~~19 The File object (not file name) to be uploaded.

26 20

~~27 - `"asc"`~~21- `file_id: optional string`

28 22

~~29 - `"desc"`~~23 Name of the file to create.

30 24

31### Returns25### Returns

32 26

~~33- `data: array of object { id, bytes, container_id, 4 more }`~~27- `id: string`

~~35 A list of container files.~~

~~37 - `id: string`~~

38 28

39 Unique identifier for the file.29 Unique identifier for the file.

40 30

~~41 - `bytes: number`~~31- `bytes: number`

42 32

43 Size of the file in bytes.33 Size of the file in bytes.

44 34

~~45 - `container_id: string`~~35- `container_id: string`

46 36

47 The container this file belongs to.37 The container this file belongs to.

48 38

~~49 - `created_at: number`~~39- `created_at: number`

50 40

51 Unix timestamp (in seconds) when the file was created.41 Unix timestamp (in seconds) when the file was created.

52 42

~~53 - `object: string`~~43- `object: string`

54 44

55 The type of this object (`container.file`).45 The type of this object (`container.file`).

56 46

~~57 - `path: string`~~47- `path: string`

58 48

59 Path of the file in the container.49 Path of the file in the container.

60 50

~~61 - `source: string`~~51- `source: string`

62 52

63 Source of the file (e.g., `user`, `assistant`).53 Source of the file (e.g., `user`, `assistant`).

64 54

~~65- `first_id: string`~~

~~67 The ID of the first file in the list.~~

~~69- `has_more: boolean`~~

~~71 Whether there are more files available.~~

~~73- `last_id: string`~~

~~75 The ID of the last file in the list.~~

~~77- `object: "list"`~~

~~79 The type of object returned, must be 'list'.~~

~~81 - `"list"`~~

83### Example55### Example

84 56

85```http57```http

86curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \58curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \

~~87 -H "Authorization: Bearer $OPENAI_API_KEY"~~59 -H 'Content-Type: application/json' \

60 -H "Authorization: Bearer $OPENAI_API_KEY" \

61 -d '{}'

88```62```

89 63

90#### Response64#### Response

91 65

92```json66```json

93{67{

~~94 "data": [~~

~~95 {~~

96 "id": "id",68 "id": "id",

97 "bytes": 0,69 "bytes": 0,

98 "container_id": "container_id",70 "container_id": "container_id",

100 "object": "object",72 "object": "object",

101 "path": "path",73 "path": "path",

102 "source": "source"74 "source": "source"

103 }

104 ],

105 "first_id": "first_id",

106 "has_more": true,

107 "last_id": "last_id",

108 "object": "list"

109}75}

110```76```

111 77

113 79

114```http80```http

115curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \81curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \

116 -H "Authorization: Bearer $OPENAI_API_KEY"82 -H "Authorization: Bearer $OPENAI_API_KEY" \

83 -F file="@example.txt"

117```84```

118 85

119#### Response86#### Response

120 87

121```json88```json

122{89{

123 "object": "list",

124 "data": [

125 {

126 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",90 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

127 "object": "container.file",91 "object": "container.file",

128 "created_at": 1747848842,92 "created_at": 1747848842,

130 "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",94 "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",

131 "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",95 "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",

132 "source": "user"96 "source": "user"

133 }

134 ],

135 "first_id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

136 "has_more": false,

137 "last_id": "cfile_682e0e8a43c88191a7978f477a09bdf5"

138}97}

139```98```

140 99

141## Create container file100## Delete a container file

142 101

143**post** `/containers/{container_id}/files`102**delete** `/containers/{container_id}/files/{file_id}`

144 103

145Create a Container File104Delete Container File

146 105

147You can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID.106### Path Parameters

107

108- `container_id: string`

109

110- `file_id: string`

111

112### Example

113

114```http

115curl https://api.openai.com/v1/containers/$CONTAINER_ID/files/$FILE_ID \

116 -X DELETE \

117 -H "Authorization: Bearer $OPENAI_API_KEY"

118```

119

120### Example

121

122```http

123curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \

124 -H "Authorization: Bearer $OPENAI_API_KEY"

125```

126

127#### Response

128

129```json

130{

131 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

132 "object": "container.file.deleted",

133 "deleted": true

134}

135```

136

137## List container files

138

139**get** `/containers/{container_id}/files`

140

141List Container files

148 142

149### Path Parameters143### Path Parameters

150 144

151- `container_id: string`145- `container_id: string`

152 146

153### Body Parameters147### Query Parameters

154 148

155- `file: optional string`149- `after: optional string`

156 150

157 The File object (not file name) to be uploaded.151 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

158 152

159- `file_id: optional string`153- `limit: optional number`

160 154

161 Name of the file to create.155 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

156

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

158

159 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.

160

161 - `"asc"`

162

163 - `"desc"`

162 164

163### Returns165### Returns

164 166

165- `id: string`167- `data: array of object { id, bytes, container_id, 4 more }`

168

169 A list of container files.

170

171 - `id: string`

166 172

167 Unique identifier for the file.173 Unique identifier for the file.

168 174

169- `bytes: number`175 - `bytes: number`

170 176

171 Size of the file in bytes.177 Size of the file in bytes.

172 178

173- `container_id: string`179 - `container_id: string`

174 180

175 The container this file belongs to.181 The container this file belongs to.

176 182

177- `created_at: number`183 - `created_at: number`

178 184

179 Unix timestamp (in seconds) when the file was created.185 Unix timestamp (in seconds) when the file was created.

180 186

181- `object: string`187 - `object: string`

182 188

183 The type of this object (`container.file`).189 The type of this object (`container.file`).

184 190

185- `path: string`191 - `path: string`

186 192

187 Path of the file in the container.193 Path of the file in the container.

188 194

189- `source: string`195 - `source: string`

190 196

191 Source of the file (e.g., `user`, `assistant`).197 Source of the file (e.g., `user`, `assistant`).

192 198

199- `first_id: string`

200

201 The ID of the first file in the list.

202

203- `has_more: boolean`

204

205 Whether there are more files available.

206

207- `last_id: string`

208

209 The ID of the last file in the list.

210

211- `object: "list"`

212

213 The type of object returned, must be 'list'.

214

215 - `"list"`

216

193### Example217### Example

194 218

195```http219```http

196curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \220curl https://api.openai.com/v1/containers/$CONTAINER_ID/files \

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

198 -H "Authorization: Bearer $OPENAI_API_KEY"221 -H "Authorization: Bearer $OPENAI_API_KEY"

199```222```

200 223

202 225

203```json226```json

204{227{

228 "data": [

229 {

205 "id": "id",230 "id": "id",

206 "bytes": 0,231 "bytes": 0,

207 "container_id": "container_id",232 "container_id": "container_id",

209 "object": "object",234 "object": "object",

210 "path": "path",235 "path": "path",

211 "source": "source"236 "source": "source"

237 }

238 ],

239 "first_id": "first_id",

240 "has_more": true,

241 "last_id": "last_id",

242 "object": "list"

212}243}

213```244```

214 245

216 247

217```http248```http

218curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \249curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \

219 -H "Authorization: Bearer $OPENAI_API_KEY" \250 -H "Authorization: Bearer $OPENAI_API_KEY"

220 -F file="@example.txt"

221```251```

222 252

223#### Response253#### Response

224 254

225```json255```json

226{256{

257 "object": "list",

258 "data": [

259 {

227 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",260 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

228 "object": "container.file",261 "object": "container.file",

229 "created_at": 1747848842,262 "created_at": 1747848842,

231 "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",264 "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04",

232 "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",265 "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json",

233 "source": "user"266 "source": "user"

267 }

268 ],

269 "first_id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

270 "has_more": false,

271 "last_id": "cfile_682e0e8a43c88191a7978f477a09bdf5"

234}272}

235```273```

236 274

318}356}

319```357```

320 358

321## Delete a container file

~~322~~

323**delete** `/containers/{container_id}/files/{file_id}`

~~324~~

325Delete Container File

~~326~~

327### Path Parameters

~~328~~

329- `container_id: string`

~~330~~

331- `file_id: string`

~~332~~

333### Example

~~334~~

335```http

336curl https://api.openai.com/v1/containers/$CONTAINER_ID/files/$FILE_ID \

337 -X DELETE \

338 -H "Authorization: Bearer $OPENAI_API_KEY"

339```

~~340~~

341### Example

~~342~~

343```http

344curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \

345 -H "Authorization: Bearer $OPENAI_API_KEY"

346```

~~347~~

348#### Response

~~349~~

350```json

351{

352 "id": "cfile_682e0e8a43c88191a7978f477a09bdf5",

353 "object": "container.file.deleted",

354 "deleted": true

355}

356```

~~357~~

358## Domain Types359## Domain Types

359 360

360### File List Response361### File Create Response

361 362

362- `FileListResponse object { id, bytes, container_id, 4 more }`363- `FileCreateResponse object { id, bytes, container_id, 4 more }`

363 364

364 - `id: string`365 - `id: string`

365 366

389 390

390 Source of the file (e.g., `user`, `assistant`).391 Source of the file (e.g., `user`, `assistant`).

391 392

392### File Create Response393### File List Response

393 394

394- `FileCreateResponse object { id, bytes, container_id, 4 more }`395- `FileListResponse object { id, bytes, container_id, 4 more }`

395 396

396 - `id: string`397 - `id: string`

397 398

resources/containers/subresources/files/index.md 2026-07-25 05:59 UTC to 2026-07-29 15:02 UTC

Files

Create container file

Path Parameters

Body Parameters

Returns

Example

Response

Example

Response

Delete a container file

Path Parameters

Example

Example

Response

List container files

Path Parameters

Query Parameters

Returns

Example

Response

Example

Response

Retrieve container file

Path Parameters

Returns

Example

Response

Example

Response

Domain Types

File Create Response

File List Response

File Retrieve Response

Content

Retrieve container file content

Path Parameters

Example

Example

Response