Skip to main content
Files (/v1/files) and Skills (/v1/skills) are Project resources with their own lifecycle, independent of Sessions. A File holds uploaded bytes that Environments copy by ID. A Skill holds immutable, versioned bundles that Templates and Sessions reference. Every API key of a Project shares them. These routes follow the SDK pinned in upstream.json: the Files resource, create parameters, FileObject and the Skills resource. They need a Project API key and no OpenAI-Beta header. A missing ID and another Project’s ID return the same 404.

​
Files

Use a File by passing its ID to Environment files or to a Template’s or Session’s initial files (Environments). Those copies read the bytes internally; the public download stays refused.

​
Upload

  • Only purpose=user_data is accepted. Other purposes, expires_after and the Uploads API are not supported.
  • The file may be empty and holds up to 512 MiB; the whole multipart body may exceed that by 64 KiB. A larger upload returns 413 request_too_large. The transfer must finish within five minutes.
  • A missing, repeated or unknown part, a Content-Encoding or Content-Transfer-Encoding header, or a filename that is empty, longer than 1,024 bytes, not UTF-8 or contains NUL returns 400. Core stores nothing until the whole request validates.
  • Core does not deduplicate uploads. After a lost response, list Files before uploading again.

​
File object

​
List Files

The response is {"object": "list", "data": [...], "first_id", "last_id", "has_more"}; an empty page has null IDs. limit, query parsing and their errors follow the shared list rules.

​
Errors

A missing or foreign File returns 404 with type invalid_request_error, a null code and param: "id" for retrieve, content and delete.

​
Storage and deletion

Core stores File bytes as PostgreSQL large objects in its own database. An upload and a deletion each commit in one transaction, so a failure leaves neither partial bytes nor metadata. Back up the database with its large objects; deleting a File does not remove it from write-ahead logs or earlier backups. The source Files schema refuses a downgrade while File rows remain. Delete Files through the API first so their large objects are removed. A copy into a workspace reads a consistent snapshot of the File and can finish after the File is deleted; later lookups fail. Deleting a File never changes a workspace copy.

​
Skills

limit, cursors and query errors follow the shared list rules.

​
Upload a bundle

Send one ZIP as a files part, or a directory as repeated files[] parts whose filenames are relative paths such as report/SKILL.md. SDK 3.13.0 sends no part when files is a single file rather than a list, so upload a single ZIP with plain HTTP:
A bundle has one top-level folder containing SKILL.md and any supporting files:
  • SKILL.md is UTF-8, at most 256 KiB, and starts with YAML front matter. name is required: lowercase letters and digits, optionally separated by single - or _, at most 64 characters. description is required and non-empty. license, compatibility and a string-valued metadata map are optional; any other key is rejected.
  • Entries are regular files or directories with clean relative paths. Links, special files, absolute paths, .. components and duplicates are rejected.
  • Limits: 5 MiB compressed, 20 MiB expanded, 500 files, and 1,000 ZIP entries including directories.
Core encrypts each version’s bundle bound to its Project, Skill and version. ZIP uploads keep executable bits; directory uploads store files with mode 0644.

​
Versions and metadata

  • Version numbers start at 1, increase by one per upload and are never reused, even after the latest version is deleted. Template and Session selectors name versions by number, so a reused number could point a stored selector at different bytes.
  • The Skill’s name and description are those of its default version. Changing the default, by POST /skills/{skill_id} or by uploading with default=true, updates the pointer and both fields together; id and created_at stay the same.
  • latest_version is the highest remaining version.
  • Uploads and deletions of one Skill run one at a time, so a deletion never removes a version whose upload was acknowledged.
How Templates and Sessions select a version (default, latest or a number) and freeze its bytes is in Environments.

​
Delete a version

Deleting a Skill or a version does not change Sessions that already installed it; Templates keep the reference they stored.