The signed storage flow allows you to upload large files (such as videos, zip files, or heavy documents) directly to cloud storage (Amazon S3) securely, without routing the file bytes through the API gateway.
Step 1: Initiate Upload Call the createSignedStorage endpoint to register the file and obtain a temporary pre-signed S3 upload URL.
Endpoint POST /v1/process/knowledges/createSignedStorageBody Parameters The unique identifier for the sub-project.
The target name of the file to create.
Mime-type of the file being uploaded.
The target storage plugin.
Response Fields The unique identifier reserved for the file.
The initial lock state of the file (will remain true until closed).
The S3 POST endpoint URL to send the file to.
The required form fields (signature, policy, keys, token) to include in the multi-part form POST request.
Request Example curl --location 'https://api.sarasfinance.com/v1/process/knowledges/createSignedStorage' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "subProjectId": "93d599a6-a396-4ef6-b30e-aff95c56c523", "fileName": "evidence.mp4", "mimeType": "video/mp4", "pluginName": "knowledgeRepo" }'
Response Example { "file" : { "id" : "file_a781b2e9" , "fileName" : "evidence.mp4" , "locked" : true }, "aws" : { "url" : "https://gf-saras-storage.s3.amazonaws.com/" , "fields" : { "key" : "uploads/evidence.mp4" , "AWSAccessKeyId" : "AKIAIOSFODNN7EXAMPLE" , "policy" : "eyJleHBpcmF0aW9uIjogIjIwMjY..." , "signature" : "vjbyPxybdZaNmGaEXAMPLE=" } } }
Step 2: Upload File to S3 Perform a standard HTTP multi-part form POST request to the AWS S3 URL returned in Step 1. You must include all key-value pairs from the aws.fields object as form fields, and append the file field last.
Request Example curl --location --request POST 'https://gf-saras-storage.s3.amazonaws.com/' \ --form 'key="uploads/evidence.mp4"' \ --form 'AWSAccessKeyId="AKIAIOSFODNN7EXAMPLE"' \ --form 'policy="eyJleHBpcmF0aW9uIjogIjIwMjY..."' \ --form 'signature="vjbyPxybdZaNmGaEXAMPLE="' \ --form 'file=@"/path/to/evidence.mp4"'
Step 3: Finalize Upload After S3 responds with a successful upload status code (204 No Content), call the closeSignedStorage endpoint to verify the file’s presence, unlock it, and retrieve its complete metadata.
Endpoint POST /v1/process/knowledges/closeSignedStorageBody Parameters The unique identifier for the sub-project.
The unique ID of the file record to close.
Response Fields The unique identifier for the file.
Total size of the uploaded file in bytes.
The finalized lock state of the file (will be unlocked: false).
Request Example curl --location 'https://api.sarasfinance.com/v1/process/knowledges/closeSignedStorage' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <token>' \ --data '{ "subProjectId": "93d599a6-a396-4ef6-b30e-aff95c56c523", "fileId": "file_a781b2e9" }'
Response Example { "file" : { "id" : "file_a781b2e9" , "fileName" : "evidence.mp4" , "size" : "52428800" , "locked" : false } }
Error Codes Code ID Description ERROR_PROCESS_META_IS_MISSING_IN_REQUEST1200 Metadata missing in request ERROR_SUBPROCESS_META_NOT_FOUND1202 Sub-project metadata not found ERROR_FILE_ID_NOT_FOUND1704 File ID does not exist ERROR_STORAGE_PRESIGN_FAILED1709 S3 URL generation failed ERROR_STORAGE_CLOSE_FAILED1715 Verification or closure of storage failed
