File upload
This section explains uploading a file to the chainsite storage.
Last updated
This section explains uploading a file to the chainsite storage.
Last updated
Chainsites are deployed with storage in mind, ensuring users can upload files to the chainsite storage server.
The maximum uploaded file size can be adjusted at the Pakt Command Centre.
The following services are offered in this section
The endpoint returns information about files that have been uploaded to the system, allowing users to browse through their uploaded content. The results are paginated to manage large collections of files efficiently.
Request
Query Parameters
page: Specifies which page of results to retrieve. In this example, page=1 requests the first page of results.
limit: Determines how many file records to return per page. In this example, limit=1 restricts the response to just one file record.
Response
The response provides a paginated list of file records along with pagination metadata:
Status Information
status: Indicates the outcome of the request. A value of "success" means the request was processed without errors.
message: Provides additional context about the request result. "OK" confirms that the operation completed as expected.
Pagination and Results Data
The "data" field contains both pagination information and the actual file records:
count: The total number of file records available across all pages. In this example, there are 2 total files in the system.
pages: The total number of pages available based on the requested limit. With 2 total files and a limit of 1 file per page, there are 2 pages available.
data: An array containing the file records for the current page. Since the limit is set to 1, this array contains only one file record:
_id: A unique database identifier for the file record, formatted as a MongoDB ObjectId.
name: The storage path and filename of the file in the storage system, including directory structure, user identifier, and a system-generated UUID filename with extension.
uploaded_by: The unique identifier of the user who uploaded the file, allowing for ownership tracking and permission management.
type: The MIME type of the file, indicating its format (in this case, "image/png" for a PNG image).
size: The size of the file in bytes, useful for tracking storage usage.
bucket: The storage bucket where the file is stored, in this case "chainsite-dev-storage" indicates a development environment.
url: A publicly accessible URL where the file can be viewed or downloaded. Note that in this example, the URL appears to be partially redacted or malformed with a hyphen replacing the domain.
meta: Additional metadata about the file:
originalName: The original filename from the user's system before upload, preserved for reference.
status: A boolean flag indicating whether the file is active and available (true) or not.
deletedAt: Timestamp indicating when the file was deleted. A null value means the file is not deleted.
createdAt: The timestamp when the file was uploaded and the record was created.
updatedAt: The timestamp when the file record was last modified.
__v: A version number for the document, used internally by MongoDB.
Usage
This endpoint is typically used to build file management interfaces, allowing users to browse, search, or manage their previously uploaded files. The pagination parameters (page and limit) enable efficient navigation through large collections of files.
By adjusting the page and limit parameters, users can retrieve different subsets of their uploaded files. For example, increasing the limit would show more files per page, while incrementing the page number would navigate through the collection.
The count and pages values help applications build appropriate pagination controls, showing users how many total files exist and how many pages they can navigate through.
110GOGOPOOLOK
The endpoint returns comprehensive metadata for a single file that has been previously uploaded to the system. This allows users or applications to access specific file details when the file ID is known.
Request
Path Parameters
id: The unique identifier of the file to retrieve. This is typically a MongoDB ObjectId that is assigned to the file record when it is created in the database.
Response
The response provides detailed information about the requested file:
Status Information
status: Indicates the outcome of the request. A value of "success" means the file was found and the information was retrieved without errors.
message: Provides additional context about the request result. "Success" confirms that the operation completed as expected.
File Data
The "data" field contains comprehensive metadata about the requested file:
_id: The unique database identifier for the file record that was used in the request. This matches the ID provided in the request path.
name: The storage path and filename of the file in the storage system. This structured path includes a public directory, the user identifier who uploaded the file, and a system-generated UUID filename with extension to ensure uniqueness.
uploaded_by: The unique identifier of the user who uploaded the file. This ID can be used to associate the file with a specific user account for ownership and access control purposes.
type: The MIME type of the file, which identifies its format and how it should be handled by applications. In this example, "image/png" indicates a PNG image file.
size: The size of the file in bytes. This information is useful for storage management and bandwidth considerations when accessing the file.
bucket: The cloud storage bucket where the file is stored. "chainsite-dev-storage" indicates this file is stored in a development environment bucket.
url: A publicly accessible URL where the file can be viewed or downloaded. Note that in this example, the URL appears to be partially redacted or malformed with a hyphen replacing the domain portion.
meta: Additional metadata about the file:
originalName: The original filename from the user's system before it was uploaded and renamed. This helps maintain a connection to the file's origin.
status: A boolean flag indicating whether the file is active and available (true) or not. This can be used to filter out inactive files without physically deleting them.
deletedAt: Timestamp indicating when the file was soft-deleted, if applicable. A null value means the file is not deleted and is still active in the system.
createdAt: The timestamp when the file was originally uploaded and the record was created in the database.
updatedAt: The timestamp when the file record was last modified. In this example, it matches the creation time, indicating the file hasn't been updated since upload.
__v: A version number for the document, used internally by MongoDB for concurrency control.
Usage
This endpoint is typically used when specific file information is needed, such as:
Displaying detailed file information in a management interface
Verifying file properties before processing
Retrieving the access URL to embed or link to the file in applications
Checking file metadata like size and type before performing operations on the file
The endpoint is particularly useful when building file management systems where users need to access, view, or manage individual files by their unique identifiers.
68123badaa855ca20cdf6451OK
Unlike the other file-related endpoints that return metadata about the file, this endpoint generates and returns a pre-signed URL that provides temporary direct access to the file stored in AWS S3. This URL contains authentication credentials embedded as query parameters that allow temporary access to the file without requiring the requester to have AWS credentials.
Request
id: The unique identifier of the file to retrieve. This is typically a MongoDB ObjectId that is assigned to the file record when it is created in the database.
Response
A successful request returns a JSON response with the following structure:
The response provides a pre-signed URL for file download:
Status Information
status: Indicates the outcome of the request. A value of "success" means the download URL was generated successfully.
message: Provides additional context about the request result. "Success" confirms that the operation completed as expected.
File Access URL
data: Unlike the file metadata retrieval endpoint with the same path, this variant returns a direct string value containing a pre-signed Amazon S3 URL. This URL contains several key components:
Base URL: The S3 bucket location where the file is stored
Object Path: The path to the specific file within the bucket ("public/680b8f5b03127a4fd7110e38/d4a6e766-4157-4a9b-9e4e-d1bccd473bae.png")
Authentication Parameters: Several query parameters that authenticate and secure the request:
X-Amz-Algorithm: The signing algorithm used (AWS4-HMAC-SHA256)
X-Amz-Content-Sha256: Content hash value
X-Amz-Credential: The AWS access key ID and scope information
X-Amz-Date: The timestamp of when the URL was generated
X-Amz-Expires: The duration in seconds that the URL remains valid (300 seconds or 5 minutes)
X-Amz-Signature: A cryptographic signature that verifies the request
X-Amz-SignedHeaders: The headers included in the signature calculation
Additional Parameters: Extra parameters like checksum mode and object ID
68123badaa855ca20cdf6451OK
This endpoint is used to upload a file for public purposes.
Request
Headers
Content-Type: multipart/form-data
Body
The request body should be formatted as multipart/form-data with the file to be uploaded included as a form field.
Response
status: Indicates the outcome of the upload operation. A value of "success" means the file was successfully uploaded and stored in the system.
message: Provides a human-readable description of the result. "file Uploaded Successfully" confirms that the operation completed as expected.
The "data" field contains comprehensive metadata about the uploaded file:
name: The storage path and filename of the uploaded file in the storage system. This includes a public directory path, user identifier, and a system-generated UUID filename with extension (e.g., "public/680b8f5b03127a4fd7110e38/ac5af6e7-08f2-42d0-9900-fdb729c82951.png").
uploaded_by: The unique identifier of the user who uploaded the file. This helps track file ownership and permissions within the system.
type: The MIME type of the uploaded file, which identifies the format and nature of the file (e.g., "image/png" for PNG images).
size: The size of the uploaded file in bytes. This can be useful for tracking storage usage and implementing file size limitations.
bucket: The storage bucket where the file is stored. In this example, "chainsite-dev-storage" indicates this is stored in a development environment bucket.
url: A publicly accessible URL where the file can be viewed or downloaded. This URL uses a content delivery network (CloudFront) to ensure fast access globally.
meta: Additional metadata about the file:
originalName: The original filename from the user's system before it was uploaded and renamed.
status: A boolean flag indicating whether the file is active and available (true) or not.
deletedAt: Timestamp indicating when the file was deleted. A null value means the file is not deleted.
_id: A unique database identifier for the file record, typically in MongoDB ObjectId format.
createdAt: The timestamp when the file was uploaded and the record was created.
updatedAt: The timestamp when the file record was last modified.
Usage Notes
The uploaded file is immediately available at the URL provided in the response.
The system automatically generates a unique identifier for each file to prevent name collisions.
Original filenames are preserved in metadata but not used in the actual storage path.
The response includes all necessary information to reference the file in future API calls.
OK
Upload a file privately. Use this endpoint if the file is sensitive or needs to be private.
Content-Type: multipart/form-data
The request body should be formatted as multipart/form-data with the file to be uploaded included as a form field.
status: Indicates the outcome of the upload operation. A value of "success" means the file was successfully uploaded and stored in the system.
message: Provides a human-readable description of the result. "file Uploaded Successfully" confirms that the operation completed as expected.
File Data
The "data" field contains comprehensive metadata about the uploaded file:
name: The storage path and filename of the uploaded file in the storage system. This includes a public directory path, user identifier, and a system-generated UUID filename with extension (e.g., "public/680b8f5b03127a4fd7110e38/ac5af6e7-08f2-42d0-9900-fdb729c82951.png").
uploaded_by: The unique identifier of the user who uploaded the file. This helps track file ownership and permissions within the system.
type: The MIME type of the uploaded file, which identifies the format and nature of the file (e.g., "image/png" for PNG images).
size: The size of the uploaded file in bytes. This can be useful for tracking storage usage and implementing file size limitations.
bucket: The storage bucket where the file is stored. In this example, "chainsite-dev-storage" indicates this is stored in a development environment bucket.
url: A publicly accessible URL where the file can be viewed or downloaded. This URL uses a content delivery network (CloudFront) to ensure fast access globally.
meta: Additional metadata about the file:
originalName: The original filename from the user's system before it was uploaded and renamed.
status: A boolean flag indicating whether the file is active and available (true) or not.
deletedAt: Timestamp indicating when the file was deleted. A null value means the file is not deleted.
_id: A unique database identifier for the file record, typically in MongoDB ObjectId format.
createdAt: The timestamp when the file was uploaded and the record was created.
updatedAt: The timestamp when the file record was last modified.
The uploaded file is immediately available at the URL provided in the response.
The system automatically generates a unique identifier for each file to prevent name collisions.
Original filenames are preserved in metadata but not used in the actual storage path.
The response includes all necessary information to reference the file in future API calls.
This endpoint is for uploading private files that the user does not want shared with others.