Signed Storage Upload Flow

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/createSignedStorage

Body Parameters

string

required

The unique identifier for the sub-project.

string

required

The target name of the file to create.

string

required

Mime-type of the file being uploaded.

string

required

The target storage plugin.

Response Fields

object

Show properties

string

The unique identifier reserved for the file.

string

The name of the file.

boolean

The initial lock state of the file (will remain true until closed).

object

Show AWS Upload Details

string

The S3 POST endpoint URL to send the file to.

object

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/closeSignedStorage

Body Parameters

string

required

The unique identifier for the sub-project.

string

required

The unique ID of the file record to close.

Response Fields

object

Show properties

string

The unique identifier for the file.

string

The final filename.

string

Total size of the uploaded file in bytes.

boolean

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_REQUEST`	1200	Metadata missing in request
`ERROR_SUBPROCESS_META_NOT_FOUND`	1202	Sub-project metadata not found
`ERROR_FILE_ID_NOT_FOUND`	1704	File ID does not exist
`ERROR_STORAGE_PRESIGN_FAILED`	1709	S3 URL generation failed
`ERROR_STORAGE_CLOSE_FAILED`	1715	Verification or closure of storage failed

​Step 1: Initiate Upload

​Endpoint

​Body Parameters

​Response Fields

​Request Example

​Response Example

​Step 2: Upload File to S3

​Request Example

​Step 3: Finalize Upload

​Endpoint

​Body Parameters

​Response Fields

​Request Example

​Response Example

​Error Codes

Step 1: Initiate Upload

Endpoint

Body Parameters

Response Fields

Request Example

Response Example

Step 2: Upload File to S3

Request Example

Step 3: Finalize Upload

Endpoint

Body Parameters

Response Fields

Request Example

Response Example

Error Codes