Documentation | Files

Files

FilesResource

Methods

client.files.create() ->

post/v5/files

Upload a file's bytes directly and create a file record.

Send the file as multipart/form-data in the file field; the request body carries the raw bytes, unlike cloud_imports which only references blobs that already exist in cloud storage. The upload is rejected if it exceeds 25 MB; larger or direct-to-storage uploads use a separate upload flow. The server detects the content type from the bytes and rejects content that fails the structural validation for that type. Content is deduplicated by checksum and MIME type, so uploading bytes identical to an existing file reuses the already-stored object instead of storing a second copy. Returns the created file's metadata.

client.files.import_from_cloud() ->

FileImportFromCloudResponse

post/v5/files/cloud_imports

Unlike upload, this transfers no bytes: each entry references an existing object by its container/bucket, filepath, filename, and MIME type, and only a metadata record pointing at that object is created. Files are imported independently and the response reports a per-file status. The response is 200 when every import succeeds and 207 when results are mixed, with each result marked SUCCESS or a failure reason (file does not exist, invalid permissions, or unknown error). Failed entries carry only the submitted filename and MIME type rather than a full file record.

client.files.list() -> SyncCursorPage[

SGPFile

]

get/v5/files

List the account's files with pagination.

Optionally filter by filename (case-insensitive partial match). Results are scoped to the files the caller is authorized to read. Files marked hidden (internal or service-owned artifacts) are excluded from this listing but remain retrievable by id. Returns file metadata only, not content.

client.files.update(, ) ->

SGPFile

patch/v5/files/{file_id}

Update a file's mutable metadata by id.

Only the file's tags can be modified; filename, content, size, and other attributes are immutable through this endpoint. The supplied tags replace the file's existing tags. Returns the updated file metadata.

Parameters

file_id: str

tags: Optional[Dict[str,

object

]]

x_project_id: Optional[str]

Returns

SGPFile

id: str

The unique identifier of the entity.

created_at:

datetime

(format: date-time)

The date and time when the entity was created in ISO format.

created_by:

Identity

The identity that created the entity.

filename: str

md5_checksum: str

mime_type: str

size: int

duration_seconds: Optional[int]

object: Optional[Literal["file"]]

(default: "file")

tags: Optional[Dict[str,

object

]]

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
sgp_file = client.files.update(
    file_id="file_id",
)
print(sgp_file.id)

200Example

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "filename": "filename",
  "md5_checksum": "md5_checksum",
  "mime_type": "mime_type",
  "size": 0,
  "duration_seconds": 0,
  "object": "file",
  "tags": {
    "foo": "bar"
  }
}

client.files.retrieve(, ) ->

SGPFile

get/v5/files/{file_id}

Retrieve a single file's metadata by id.

Returns the file record (id, filename, MIME type, size, tags, and related fields) but not the file's bytes; use the content endpoint to download the bytes.

client.files.delete(, ) ->

FileDeleteResponse

delete/v5/files/{file_id}

Delete a file by id, removing its database record.

This is a hard delete: the file's row is removed from the database, not soft-archived. The underlying stored object is deleted only when no other file record still references the same stored content (identical checksum and MIME type); when another record shares the blob, the blob is retained. If the id refers to an incomplete multipart upload placeholder, its staged parts are aborted instead. Returns a confirmation carrying the deleted file's id.

Domain types

class FileDeleteResponse: ...

class FileImportFromCloudResponse: ...

class SGPFile: ...

Files

Content

FilesResource.ContentResource

Methods

client.files.content.retrieve(, ) ->

object

get/v5/files/{file_id}/content

Download the raw bytes of a file by id.

Streams the stored object's content back directly (not a redirect or signed URL), with the response Content-Type set to the file's stored MIME type and Content-Disposition set to attachment. Use the metadata endpoint for size, filename, and other attributes.

Domain types