# Files

## Upload file bytes directly

`files.create(FileCreateParams**kwargs)  -> SGPFile`

**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.

### Parameters

- `file: FileTypes`

- `x_project_id: Optional[str]`

### Returns

- `class SGPFile: …`

  - `id: str`

    The unique identifier of the entity.

  - `created_at: datetime`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `filename: str`

  - `md5_checksum: str`

  - `mime_type: str`

  - `size: int`

  - `duration_seconds: Optional[int]`

  - `object: Optional[Literal["file"]]`

    - `"file"`

  - `tags: Optional[Dict[str, object]]`

### Example

```python
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.create(
    file=b"Example data",
)
print(sgp_file.id)
```

#### Response

```json
{
  "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"
  }
}
```

## Import files from cloud storage

`files.import_from_cloud(FileImportFromCloudParams**kwargs)  -> FileImportFromCloudResponse`

**post** `/v5/files/cloud_imports`

Register files that already exist in cloud blob storage as file records, in one batch.

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.

### Parameters

- `files: Iterable[File]`

  List of files to import from cloud storage

  - `container: str`

    The cloud storage container/bucket name

  - `file_type: str`

    The MIME type of the file

  - `filename: str`

    The name of the file

  - `filepath: str`

    The path to the file within the container

- `x_project_id: Optional[str]`

### Returns

- `class FileImportFromCloudResponse: …`

  - `results: List[Result]`

    Results for each file import attempt

    - `file: ResultFile`

      The file object (full File for success, minimal _FailedFile for failures)

      - `class SGPFile: …`

        - `id: str`

          The unique identifier of the entity.

        - `created_at: datetime`

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

        - `created_by: Identity`

          The identity that created the entity.

          - `id: str`

          - `type: Literal["user", "service_account"]`

            - `"user"`

            - `"service_account"`

          - `object: Optional[Literal["identity"]]`

            - `"identity"`

        - `filename: str`

        - `md5_checksum: str`

        - `mime_type: str`

        - `size: int`

        - `duration_seconds: Optional[int]`

        - `object: Optional[Literal["file"]]`

          - `"file"`

        - `tags: Optional[Dict[str, object]]`

      - `class ResultFile_FailedFile: …`

        Minimal file representation for failed uploads containing only essential information.

        - `filename: str`

          The original filename from the request

        - `mime_type: str`

          The original MIME type from the request

        - `object: Optional[Literal["failed_file"]]`

          - `"failed_file"`

    - `status: Literal["SUCCESS", "FAILED_FILE_DOES_NOT_EXIST", "FAILED_INVALID_PERMISSIONS", "FAILED_UNKNOWN_ERROR"]`

      The status of the upload attempt

      - `"SUCCESS"`

      - `"FAILED_FILE_DOES_NOT_EXIST"`

      - `"FAILED_INVALID_PERMISSIONS"`

      - `"FAILED_UNKNOWN_ERROR"`

### Example

```python
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
)
response = client.files.import_from_cloud(
    files=[{
        "container": "container",
        "file_type": "file_type",
        "filename": "filename",
        "filepath": "filepath",
    }],
)
print(response.results)
```

#### Response

```json
{
  "results": [
    {
      "file": {
        "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"
        }
      },
      "status": "SUCCESS"
    }
  ]
}
```

## List files

`files.list(FileListParams**kwargs)  -> 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.

### Parameters

- `ending_before: Optional[str]`

- `filename: Optional[str]`

  Filter files by filename (case-insensitive partial match)

- `limit: Optional[int]`

- `sort_by: Optional[str]`

- `sort_order: Optional[SortOrder]`

  - `"asc"`

  - `"desc"`

- `starting_after: Optional[str]`

- `x_project_id: Optional[str]`

### Returns

- `class SGPFile: …`

  - `id: str`

    The unique identifier of the entity.

  - `created_at: datetime`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `filename: str`

  - `md5_checksum: str`

  - `mime_type: str`

  - `size: int`

  - `duration_seconds: Optional[int]`

  - `object: Optional[Literal["file"]]`

    - `"file"`

  - `tags: Optional[Dict[str, object]]`

### Example

```python
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
)
page = client.files.list()
page = page.items[0]
print(page.id)
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "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"
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}
```

## Update a file

`files.update(strfile_id, FileUpdateParams**kwargs)  -> 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

- `class SGPFile: …`

  - `id: str`

    The unique identifier of the entity.

  - `created_at: datetime`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `filename: str`

  - `md5_checksum: str`

  - `mime_type: str`

  - `size: int`

  - `duration_seconds: Optional[int]`

  - `object: Optional[Literal["file"]]`

    - `"file"`

  - `tags: Optional[Dict[str, object]]`

### Example

```python
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)
```

#### Response

```json
{
  "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"
  }
}
```

## Get file metadata

`files.retrieve(strfile_id, FileRetrieveParams**kwargs)  -> 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.

### Parameters

- `file_id: str`

- `x_project_id: Optional[str]`

### Returns

- `class SGPFile: …`

  - `id: str`

    The unique identifier of the entity.

  - `created_at: datetime`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `filename: str`

  - `md5_checksum: str`

  - `mime_type: str`

  - `size: int`

  - `duration_seconds: Optional[int]`

  - `object: Optional[Literal["file"]]`

    - `"file"`

  - `tags: Optional[Dict[str, object]]`

### Example

```python
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.retrieve(
    file_id="file_id",
)
print(sgp_file.id)
```

#### Response

```json
{
  "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"
  }
}
```

## Delete a file

`files.delete(strfile_id, FileDeleteParams**kwargs)  -> 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.

### Parameters

- `file_id: str`

- `x_project_id: Optional[str]`

### Returns

- `class FileDeleteResponse: …`

  - `id: str`

  - `deleted: bool`

  - `object: Optional[Literal["file"]]`

    - `"file"`

### Example

```python
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
)
file = client.files.delete(
    file_id="file_id",
)
print(file.id)
```

#### Response

```json
{
  "id": "id",
  "deleted": true,
  "object": "file"
}
```

## Domain Types

### SGP File

- `class SGPFile: …`

  - `id: str`

    The unique identifier of the entity.

  - `created_at: datetime`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: str`

    - `type: Literal["user", "service_account"]`

      - `"user"`

      - `"service_account"`

    - `object: Optional[Literal["identity"]]`

      - `"identity"`

  - `filename: str`

  - `md5_checksum: str`

  - `mime_type: str`

  - `size: int`

  - `duration_seconds: Optional[int]`

  - `object: Optional[Literal["file"]]`

    - `"file"`

  - `tags: Optional[Dict[str, object]]`

### File Import From Cloud Response

- `class FileImportFromCloudResponse: …`

  - `results: List[Result]`

    Results for each file import attempt

    - `file: ResultFile`

      The file object (full File for success, minimal _FailedFile for failures)

      - `class SGPFile: …`

        - `id: str`

          The unique identifier of the entity.

        - `created_at: datetime`

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

        - `created_by: Identity`

          The identity that created the entity.

          - `id: str`

          - `type: Literal["user", "service_account"]`

            - `"user"`

            - `"service_account"`

          - `object: Optional[Literal["identity"]]`

            - `"identity"`

        - `filename: str`

        - `md5_checksum: str`

        - `mime_type: str`

        - `size: int`

        - `duration_seconds: Optional[int]`

        - `object: Optional[Literal["file"]]`

          - `"file"`

        - `tags: Optional[Dict[str, object]]`

      - `class ResultFile_FailedFile: …`

        Minimal file representation for failed uploads containing only essential information.

        - `filename: str`

          The original filename from the request

        - `mime_type: str`

          The original MIME type from the request

        - `object: Optional[Literal["failed_file"]]`

          - `"failed_file"`

    - `status: Literal["SUCCESS", "FAILED_FILE_DOES_NOT_EXIST", "FAILED_INVALID_PERMISSIONS", "FAILED_UNKNOWN_ERROR"]`

      The status of the upload attempt

      - `"SUCCESS"`

      - `"FAILED_FILE_DOES_NOT_EXIST"`

      - `"FAILED_INVALID_PERMISSIONS"`

      - `"FAILED_UNKNOWN_ERROR"`

### File Delete Response

- `class FileDeleteResponse: …`

  - `id: str`

  - `deleted: bool`

  - `object: Optional[Literal["file"]]`

    - `"file"`

# Content

## Download file content

`files.content.retrieve(strfile_id, ContentRetrieveParams**kwargs)  -> 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.

### Parameters

- `file_id: str`

- `x_project_id: Optional[str]`

### Returns

- `object`

### Example

```python
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
)
content = client.files.content.retrieve(
    file_id="file_id",
)
print(content)
```

#### Response

```json
{}
```