Versions

Create a new immutable skill version.

post /skills/{skill_id}/versions

Create a new immutable skill version.

Path Parameters

skill_id: string

Body Parameters

files: array of string or string

Skill files to upload (directory upload) or a single zip file.
- array of string
  
  Skill files to upload (directory upload) or a single zip file.
- string
  
  Skill zip file to upload.
default: optional boolean

Whether to set this version as the default.

Returns

SkillVersion object { id, created_at, description, 4 more }
- id: string
  
  Unique identifier for the skill version.
- created_at: number
  
  Unix timestamp (seconds) for when the version was created.
- description: string
  
  Description of the skill version.
- name: string
  
  Name of the skill version.
- object: "skill.version"
  
  The object type, which is skill.version.
  - "skill.version"
- skill_id: string
  
  Identifier of the skill for this version.
- version: string
  
  Version number for this skill.

Example

curl https://api.openai.com/v1/skills/$SKILL_ID/versions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F files='["Example data"]'

Response

{
  "id": "id",
  "created_at": 0,
  "description": "description",
  "name": "name",
  "object": "skill.version",
  "skill_id": "skill_id",
  "version": "version"
}

List skill versions for a skill.

get /skills/{skill_id}/versions

List skill versions for a skill.

Path Parameters

skill_id: string

Query Parameters

after: optional string

The skill version ID to start after.
limit: optional number

Number of versions to retrieve.
order: optional "asc" or "desc"

Sort order of results by version number.
- "asc"
- "desc"

Returns

SkillVersionList object { data, first_id, has_more, 2 more }
- data: array of SkillVersion
  
  A list of items
  - id: string
    
    Unique identifier for the skill version.
  - created_at: number
    
    Unix timestamp (seconds) for when the version was created.
  - description: string
    
    Description of the skill version.
  - name: string
    
    Name of the skill version.
  - object: "skill.version"
    
    The object type, which is skill.version.
    - "skill.version"
  - skill_id: string
    
    Identifier of the skill for this version.
  - version: string
    
    Version number for this skill.
- first_id: string
  
  The ID of the first item in the list.
- has_more: boolean
  
  Whether there are more items available.
- last_id: string
  
  The ID of the last item in the list.
- object: "list"
  
  The type of object returned, must be list.
  - "list"

Example

curl https://api.openai.com/v1/skills/$SKILL_ID/versions \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "id",
      "created_at": 0,
      "description": "description",
      "name": "name",
      "object": "skill.version",
      "skill_id": "skill_id",
      "version": "version"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

Get a specific skill version.

get /skills/{skill_id}/versions/{version}

Get a specific skill version.

Path Parameters

skill_id: string
version: string

The version number to retrieve.

Returns

SkillVersion object { id, created_at, description, 4 more }
- id: string
  
  Unique identifier for the skill version.
- created_at: number
  
  Unix timestamp (seconds) for when the version was created.
- description: string
  
  Description of the skill version.
- name: string
  
  Name of the skill version.
- object: "skill.version"
  
  The object type, which is skill.version.
  - "skill.version"
- skill_id: string
  
  Identifier of the skill for this version.
- version: string
  
  Version number for this skill.

Example

curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "created_at": 0,
  "description": "description",
  "name": "name",
  "object": "skill.version",
  "skill_id": "skill_id",
  "version": "version"
}

Delete a skill version.

delete /skills/{skill_id}/versions/{version}

Delete a skill version.

Path Parameters

skill_id: string
version: string

The skill version number.

Returns

DeletedSkillVersion object { id, deleted, object, version }
- id: string
- deleted: boolean
- object: "skill.version.deleted"
  - "skill.version.deleted"
- version: string
  
  The deleted skill version.

Example

curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION \
    -X DELETE \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "deleted": true,
  "object": "skill.version.deleted",
  "version": "version"
}

Domain Types

Deleted Skill Version

DeletedSkillVersion object { id, deleted, object, version }
- id: string
- deleted: boolean
- object: "skill.version.deleted"
  - "skill.version.deleted"
- version: string
  
  The deleted skill version.

Skill Version

SkillVersion object { id, created_at, description, 4 more }
- id: string
  
  Unique identifier for the skill version.
- created_at: number
  
  Unix timestamp (seconds) for when the version was created.
- description: string
  
  Description of the skill version.
- name: string
  
  Name of the skill version.
- object: "skill.version"
  
  The object type, which is skill.version.
  - "skill.version"
- skill_id: string
  
  Identifier of the skill for this version.
- version: string
  
  Version number for this skill.

Skill Version List

SkillVersionList object { data, first_id, has_more, 2 more }
- data: array of SkillVersion
  
  A list of items
  - id: string
    
    Unique identifier for the skill version.
  - created_at: number
    
    Unix timestamp (seconds) for when the version was created.
  - description: string
    
    Description of the skill version.
  - name: string
    
    Name of the skill version.
  - object: "skill.version"
    
    The object type, which is skill.version.
    - "skill.version"
  - skill_id: string
    
    Identifier of the skill for this version.
  - version: string
    
    Version number for this skill.
- first_id: string
  
  The ID of the first item in the list.
- has_more: boolean
  
  Whether there are more items available.
- last_id: string
  
  The ID of the last item in the list.
- object: "list"
  
  The type of object returned, must be list.
  - "list"

Content

Download a skill version zip bundle.

get /skills/{skill_id}/versions/{version}/content

Download a skill version zip bundle.

Path Parameters

skill_id: string
version: string

The skill version number.

Example

curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
    -H "Authorization: Bearer $OPENAI_API_KEY"

resources/skills/subresources/versions/index.md +448 −0 created

1# Versions

3## Create a new immutable skill version.

5**post** `/skills/{skill_id}/versions`

7Create a new immutable skill version.

9### Path Parameters

11- `skill_id: string`

13### Body Parameters

15- `files: array of string or string`

17 Skill files to upload (directory upload) or a single zip file.

19 - `array of string`

21 Skill files to upload (directory upload) or a single zip file.

23 - `string`

25 Skill zip file to upload.

27- `default: optional boolean`

29 Whether to set this version as the default.

31### Returns

33- `SkillVersion object { id, created_at, description, 4 more }`

35 - `id: string`

37 Unique identifier for the skill version.

39 - `created_at: number`

41 Unix timestamp (seconds) for when the version was created.

43 - `description: string`

45 Description of the skill version.

47 - `name: string`

49 Name of the skill version.

51 - `object: "skill.version"`

53 The object type, which is `skill.version`.

55 - `"skill.version"`

57 - `skill_id: string`

59 Identifier of the skill for this version.

61 - `version: string`

63 Version number for this skill.

65### Example

67```http

68curl https://api.openai.com/v1/skills/$SKILL_ID/versions \

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

70 -H "Authorization: Bearer $OPENAI_API_KEY" \

71 -F files='["Example data"]'

72```

74#### Response

76```json

77{

78 "id": "id",

79 "created_at": 0,

80 "description": "description",

81 "name": "name",

82 "object": "skill.version",

83 "skill_id": "skill_id",

84 "version": "version"

85}

86```

88## List skill versions for a skill.

90**get** `/skills/{skill_id}/versions`

92List skill versions for a skill.

94### Path Parameters

96- `skill_id: string`

98### Query Parameters

100- `after: optional string`

101

102 The skill version ID to start after.

103

104- `limit: optional number`

105

106 Number of versions to retrieve.

107

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

109

110 Sort order of results by version number.

111

112 - `"asc"`

113

114 - `"desc"`

115

116### Returns

117

118- `SkillVersionList object { data, first_id, has_more, 2 more }`

119

120 - `data: array of SkillVersion`

121

122 A list of items

123

124 - `id: string`

125

126 Unique identifier for the skill version.

127

128 - `created_at: number`

129

130 Unix timestamp (seconds) for when the version was created.

131

132 - `description: string`

133

134 Description of the skill version.

135

136 - `name: string`

137

138 Name of the skill version.

139

140 - `object: "skill.version"`

141

142 The object type, which is `skill.version`.

143

144 - `"skill.version"`

145

146 - `skill_id: string`

147

148 Identifier of the skill for this version.

149

150 - `version: string`

151

152 Version number for this skill.

153

154 - `first_id: string`

155

156 The ID of the first item in the list.

157

158 - `has_more: boolean`

159

160 Whether there are more items available.

161

162 - `last_id: string`

163

164 The ID of the last item in the list.

165

166 - `object: "list"`

167

168 The type of object returned, must be `list`.

169

170 - `"list"`

171

172### Example

173

174```http

175curl https://api.openai.com/v1/skills/$SKILL_ID/versions \

176 -H "Authorization: Bearer $OPENAI_API_KEY"

177```

178

179#### Response

180

181```json

182{

183 "data": [

184 {

185 "id": "id",

186 "created_at": 0,

187 "description": "description",

188 "name": "name",

189 "object": "skill.version",

190 "skill_id": "skill_id",

191 "version": "version"

192 }

193 ],

194 "first_id": "first_id",

195 "has_more": true,

196 "last_id": "last_id",

197 "object": "list"

198}

199```

200

201## Get a specific skill version.

202

203**get** `/skills/{skill_id}/versions/{version}`

204

205Get a specific skill version.

206

207### Path Parameters

208

209- `skill_id: string`

210

211- `version: string`

212

213 The version number to retrieve.

214

215### Returns

216

217- `SkillVersion object { id, created_at, description, 4 more }`

218

219 - `id: string`

220

221 Unique identifier for the skill version.

222

223 - `created_at: number`

224

225 Unix timestamp (seconds) for when the version was created.

226

227 - `description: string`

228

229 Description of the skill version.

230

231 - `name: string`

232

233 Name of the skill version.

234

235 - `object: "skill.version"`

236

237 The object type, which is `skill.version`.

238

239 - `"skill.version"`

240

241 - `skill_id: string`

242

243 Identifier of the skill for this version.

244

245 - `version: string`

246

247 Version number for this skill.

248

249### Example

250

251```http

252curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION \

253 -H "Authorization: Bearer $OPENAI_API_KEY"

254```

255

256#### Response

257

258```json

259{

260 "id": "id",

261 "created_at": 0,

262 "description": "description",

263 "name": "name",

264 "object": "skill.version",

265 "skill_id": "skill_id",

266 "version": "version"

267}

268```

269

270## Delete a skill version.

271

272**delete** `/skills/{skill_id}/versions/{version}`

273

274Delete a skill version.

275

276### Path Parameters

277

278- `skill_id: string`

279

280- `version: string`

281

282 The skill version number.

283

284### Returns

285

286- `DeletedSkillVersion object { id, deleted, object, version }`

287

288 - `id: string`

289

290 - `deleted: boolean`

291

292 - `object: "skill.version.deleted"`

293

294 - `"skill.version.deleted"`

295

296 - `version: string`

297

298 The deleted skill version.

299

300### Example

301

302```http

303curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION \

304 -X DELETE \

305 -H "Authorization: Bearer $OPENAI_API_KEY"

306```

307

308#### Response

309

310```json

311{

312 "id": "id",

313 "deleted": true,

314 "object": "skill.version.deleted",

315 "version": "version"

316}

317```

318

319## Domain Types

320

321### Deleted Skill Version

322

323- `DeletedSkillVersion object { id, deleted, object, version }`

324

325 - `id: string`

326

327 - `deleted: boolean`

328

329 - `object: "skill.version.deleted"`

330

331 - `"skill.version.deleted"`

332

333 - `version: string`

334

335 The deleted skill version.

336

337### Skill Version

338

339- `SkillVersion object { id, created_at, description, 4 more }`

340

341 - `id: string`

342

343 Unique identifier for the skill version.

344

345 - `created_at: number`

346

347 Unix timestamp (seconds) for when the version was created.

348

349 - `description: string`

350

351 Description of the skill version.

352

353 - `name: string`

354

355 Name of the skill version.

356

357 - `object: "skill.version"`

358

359 The object type, which is `skill.version`.

360

361 - `"skill.version"`

362

363 - `skill_id: string`

364

365 Identifier of the skill for this version.

366

367 - `version: string`

368

369 Version number for this skill.

370

371### Skill Version List

372

373- `SkillVersionList object { data, first_id, has_more, 2 more }`

374

375 - `data: array of SkillVersion`

376

377 A list of items

378

379 - `id: string`

380

381 Unique identifier for the skill version.

382

383 - `created_at: number`

384

385 Unix timestamp (seconds) for when the version was created.

386

387 - `description: string`

388

389 Description of the skill version.

390

391 - `name: string`

392

393 Name of the skill version.

394

395 - `object: "skill.version"`

396

397 The object type, which is `skill.version`.

398

399 - `"skill.version"`

400

401 - `skill_id: string`

402

403 Identifier of the skill for this version.

404

405 - `version: string`

406

407 Version number for this skill.

408

409 - `first_id: string`

410

411 The ID of the first item in the list.

412

413 - `has_more: boolean`

414

415 Whether there are more items available.

416

417 - `last_id: string`

418

419 The ID of the last item in the list.

420

421 - `object: "list"`

422

423 The type of object returned, must be `list`.

424

425 - `"list"`

426

427# Content

428

429## Download a skill version zip bundle.

430

431**get** `/skills/{skill_id}/versions/{version}/content`

432

433Download a skill version zip bundle.

434

435### Path Parameters

436

437- `skill_id: string`

438

439- `version: string`

440

441 The skill version number.

442

443### Example

444

445```http

446curl https://api.openai.com/v1/skills/$SKILL_ID/versions/$VERSION/content \

447 -H "Authorization: Bearer $OPENAI_API_KEY"

448```

resources/skills/subresources/versions/index.md 2026-05-02 05:57 UTC to 2026-05-05 23:00 UTC

Versions

Create a new immutable skill version.

Path Parameters

Body Parameters

Returns

Example

Response

List skill versions for a skill.

Path Parameters

Query Parameters

Returns

Example

Response

Get a specific skill version.

Path Parameters

Returns

Example

Response

Delete a skill version.

Path Parameters

Returns

Example

Response

Domain Types

Deleted Skill Version

Skill Version

Skill Version List

Content

Download a skill version zip bundle.

Path Parameters

Example