SPB Git forge
spboucher.ai ↗

spb/doc-api

Public
2commits 1branches 0releases
15.7 MBsize
maindefault branch
13 days agolast push
Python 88.3% TypeScript 7.6% Shell 4.1%
4.5 KB
View source Raw Blame History

# Skills API (/v1/skills) — versioned skill bundles for hosted shell and containers

Status: DOCUMENTED · LIVE_VERIFIED for create / retrieve / list / content / version create / delete (2026-09-18) · FAILED_VERIFICATION for GET …/versions (empty list), GET|DELETE …/versions/{version} and POST /v1/skills/{skill_id} (404 "version not found") — see discrepancies. GET …/versions/{version}/content DOCUMENTED (not called). Sources: https://developers.openai.com/api/reference/resources/skills · https://developers.openai.com/api/docs/guides/tools-skills · openapi-master.yaml paths /skills*, schemas CreateSkillBody, CreateSkillVersionBody, SetDefaultSkillVersionBody, SkillResource, SkillVersionResource, DeletedSkillResource, DeletedSkillVersionResource Last verified: 2026-09-18 · fragment: generated/fragments/endpoints/openai-containers-skills.json

# Endpoints

Method / path operationId Body / query Response Live 2026-09-18
POST /v1/skills CreateSkill multipart files = one zip or files[] directory upload (≤ 500 files) skill 200 (zip; default_version: "1", latest_version: "1")
GET /v1/skills ListSkills limit, order asc|desc, after {object:"list", data[], first_id, last_id, has_more} 200 but data: [] right after creating a skill (3 runs)
GET /v1/skills/{skill_id} GetSkill skill 200
POST /v1/skills/{skill_id} UpdateSkillDefaultVersion JSON {default_version*: "<n>"} skill 404 "Skill version '2' was not found" immediately after version 2 was created
DELETE /v1/skills/{skill_id} DeleteSkill {object:"skill.deleted", deleted:true, id} 200
GET /v1/skills/{skill_id}/content GetSkillContent application/zip 200 (PK header)
POST /v1/skills/{skill_id}/versions CreateSkillVersion multipart files (+ default boolean) skill.version (version: "2", id: skillver_…) 200
GET /v1/skills/{skill_id}/versions ListSkillVersions limit, order, after (version id) list of skill.version 200 but data: [] (3 runs, even after version 2 existed)
GET /v1/skills/{skill_id}/versions/{version} GetSkillVersion skill.version 404 for /versions/1
DELETE /v1/skills/{skill_id}/versions/{version} DeleteSkillVersion {object:"skill.version.deleted", deleted, id, version} 404 for /versions/1 (default version is documented as non-deletable anyway)
GET /v1/skills/{skill_id}/versions/{version}/content GetSkillVersionContent application/zip not called

SDK (Node, verified): client.skills.create({files}), .retrieve, .list, .delete, client.skills.versions.create/list, client.skills.content.retrieve (returns a Response, content-type: application/zip). Python SDK 3.16.2 exposes client.skills.* too (example uses raw HTTP).

# Objects (live)

json
{"id":"skill_…","object":"skill","created_at":1789782267,"name":"atlas-hello","description":"Atlas test skill. Prints OK when asked.","default_version":"1","latest_version":"1"}
{"id":"skillver_…","object":"skill.version","created_at":1789782269,"skill_id":"skill_…","version":"2","name":"atlas-hello","description":"…"}

name/description come from the SKILL.md frontmatter inside the zip (atlas-hello/SKILL.md).

# Discrepancies / uncertainties (recorded verbatim)

  1. GET /v1/skills and GET /v1/skills/{id}/versions returned empty data in every run (sh, py, ts, probe) although GET /v1/skills/{id} succeeded and versions were created. Possible eventual consistency of list indexes or a scoping difference (project vs org) — not resolved.
  2. Version endpoints addressed by number (/versions/1, default_version: "2") returned 404 seconds after creation. Whether they expect the skillver_… id or need propagation time is unknown; the spec describes {version} as "the version number".
  3. Curl uploads must not send Content-Type: application/json (the repo oai helper does) → unsupported_content_type; use plain curl -F files=@skill.zip.

# Bundle rules (docs)

Exactly one SKILL.md/skill.md; ≤ 500 files per version; ≤ 25 MB uncompressed; versions immutable; default_version used when the reference omits version; you cannot delete the default version. Usage in Responses: skills.

Examples: examples/openai/tools/skills/ (sh/py/ts, all cleaned up their skills). Raw: tmp-live/tools/skill_*.json.