Files · Ephemeral docs

Upload files to your organization and manage them. Member and admin keys can use every endpoint on this page. See files for how runs mount them.

The file object

idstring

File ID, such as file_9c41d2a07be35f1e8a6c0d4b9e2f7a13.

namestring

Relative path used as the file's name, such as guides/refunds.md.

sizeinteger

Size in bytes.

content_typestring

Detected from the file contents when it was uploaded.

created_attimestamp

When it was uploaded.

Upload a file

POST/v1/files

Stores a file of up to 1 MiB. Send it as multipart/form-data.

Form fields

filefilerequired

The file contents.

namestring

The name to store it under. Defaults to the uploaded file name. Must be a relative path of up to 240 characters.

curl $EPHEMERAL_URL/v1/files \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -F [email protected] \
  -F name=guides/refunds.md

The response is 201 Created with the file object. Uploading again under an existing name adds a new file with a new ID; the older upload is kept.

JSON

{
  "id": "file_9c41d2a07be35f1e8a6c0d4b9e2f7a13",
  "name": "guides/refunds.md",
  "size": 18234,
  "content_type": "text/plain; charset=utf-8",
  "created_at": "2026-10-03T08:02:17.553Z"
}

List files

GET/v1/files

Returns an array of file objects with the latest upload for each name, sorted by name.

Download a file

GET/v1/files/{id}

Returns the raw contents as an attachment, with the stored content type. You can pass a name instead of an ID to get the latest upload with that name.

Terminal

curl $EPHEMERAL_URL/v1/files/file_9c41d2a07be35f1e8a6c0d4b9e2f7a13 \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" -o refunds.md

Rename a file

PATCH/v1/files/{id}

Changes the name of one upload. Takes an ID.

Body

namestringrequired

The new name. A relative path of up to 240 characters.

The response is {"id": "...", "name": "..."}. Workflows that refer to the file by its old name stop finding it, while references by ID keep working.

Delete a file

DELETE/v1/files/{id}

Deletes one upload and its contents and returns 204 No Content. Takes an ID.

Queued runs that reference the file fail when they start, and later runs that name it fail at creation with 400. If an older upload with the same name exists, references by name resolve to that one instead.