# Files ## Upload file bytes directly `client.files.create(FileCreateParamsparams, RequestOptionsoptions?): 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 - `params: FileCreateParams` - `file: Uploadable` Body param - `xProjectID?: string` Header param ### Returns - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const sgpFile = await client.files.create({ file: fs.createReadStream('path/to/file') }); console.log(sgpFile.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 `client.files.importFromCloud(FileImportFromCloudParamsparams, RequestOptionsoptions?): 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 - `params: FileImportFromCloudParams` - `files: Array` Body param: List of files to import from cloud storage - `container: string` The cloud storage container/bucket name - `file_type: string` The MIME type of the file - `filename: string` The name of the file - `filepath: string` The path to the file within the container - `xProjectID?: string` Header param ### Returns - `FileImportFromCloudResponse` - `results: Array` Results for each file import attempt - `file: SGPFile | _FailedFile` The file object (full File for success, minimal _FailedFile for failures) - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` - `_FailedFile` Minimal file representation for failed uploads containing only essential information. - `filename: string` The original filename from the request - `mime_type: string` The original MIME type from the request - `object?: "failed_file"` - `"failed_file"` - `status: "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 ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const response = await client.files.importFromCloud({ files: [ { container: 'container', file_type: 'file_type', filename: 'filename', filepath: 'filepath', }, ], }); console.log(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 `client.files.list(FileListParamsparams?, RequestOptionsoptions?): CursorPage` **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 - `params: FileListParams` - `ending_before?: string` Query param - `filename?: string` Query param: Filter files by filename (case-insensitive partial match) - `limit?: number` Query param - `sort_by?: string` Query param - `sort_order?: SortOrder` Query param - `"asc"` - `"desc"` - `starting_after?: string` Query param - `xProjectID?: string` Header param ### Returns - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const sgpFile of client.files.list()) { console.log(sgpFile.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 `client.files.update(stringfileID, FileUpdateParamsparams, RequestOptionsoptions?): 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 - `fileID: string` - `params: FileUpdateParams` - `tags?: Record` Body param - `xProjectID?: string` Header param ### Returns - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const sgpFile = await client.files.update('file_id'); console.log(sgpFile.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 `client.files.retrieve(stringfileID, FileRetrieveParamsparams?, RequestOptionsoptions?): 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 - `fileID: string` - `params: FileRetrieveParams` - `xProjectID?: string` ### Returns - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const sgpFile = await client.files.retrieve('file_id'); console.log(sgpFile.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 `client.files.delete(stringfileID, FileDeleteParamsparams?, RequestOptionsoptions?): 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 - `fileID: string` - `params: FileDeleteParams` - `xProjectID?: string` ### Returns - `FileDeleteResponse` - `id: string` - `deleted: boolean` - `object?: "file"` - `"file"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const file = await client.files.delete('file_id'); console.log(file.id); ``` #### Response ```json { "id": "id", "deleted": true, "object": "file" } ``` ## Domain Types ### SGP File - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` ### File Import From Cloud Response - `FileImportFromCloudResponse` - `results: Array` Results for each file import attempt - `file: SGPFile | _FailedFile` The file object (full File for success, minimal _FailedFile for failures) - `SGPFile` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `filename: string` - `md5_checksum: string` - `mime_type: string` - `size: number` - `duration_seconds?: number` - `object?: "file"` - `"file"` - `tags?: Record` - `_FailedFile` Minimal file representation for failed uploads containing only essential information. - `filename: string` The original filename from the request - `mime_type: string` The original MIME type from the request - `object?: "failed_file"` - `"failed_file"` - `status: "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 - `FileDeleteResponse` - `id: string` - `deleted: boolean` - `object?: "file"` - `"file"` # Content ## Download file content `client.files.content.retrieve(stringfileID, ContentRetrieveParamsparams?, RequestOptionsoptions?): ContentRetrieveResponse` **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 - `fileID: string` - `params: ContentRetrieveParams` - `xProjectID?: string` ### Returns - `ContentRetrieveResponse = unknown` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const content = await client.files.content.retrieve('file_id'); console.log(content); ``` #### Response ```json {} ``` ## Domain Types ### Content Retrieve Response - `ContentRetrieveResponse = unknown`