Files

File operations (upload and download) follow a two-step process involving a Signed Access Signature (SAS) URL.

Request Flow (Upload)

Request URL: Call POST /files to get a signed upload URL (uploadUrl) and a fileId.
Upload Content: PUT your file binary directly to the uploadUrl with the header x-ms-blob-type: BlockBlob. The URL is in the format https://blobs.bevaya.ai/{organization_id}/{blob_path}?{sas_token} and expires after 15 minutes.

Request Flow (Download)

Request Metadata: Call GET /files/{fileId} to retrieve file metadata, which includes a downloadUrl.
Download Content: GET the downloadUrl to download the file content directly from storage.

Get SAS URL for file upload

POST

https://platform.bevaya.ai/api/v1

/files

Request a signed URL to upload a file. After receiving the uploadUrl, PUT your file content directly to it with the x-ms-blob-type: BlockBlob header. Flow: 1. POST /files - Get presigned upload URL 2. PUT {uploadUrl} - Upload file directly to Azure with headers: - x-ms-blob-type: BlockBlob - Content-Type: application/octet-stream (or actual MIME type)

The returned URL is valid for 15 minutes (write SAS token).

Get SAS URL for file upload › Request Body

filename

string · required

Name of the file with extension. Required for validation and MIME type detection. Example: document.pdf.

workspaceId

string · required

The workspace to associate the uploaded file with. Format: UUID. Example: 2b8d1514-6231-5c79-9108-5110495d6789.

category

client.FileCategory · enum

Enum values:

KNOWLEDGE

CONTEXT

HELPER

DOCUMENT_PROCESSING

itemId

string

Optional item ID to associate the file with. Format: UUID. Example: 6f215958-0675-90b3-3542-955483910123.

parentFileId

string

Optional parent file ID, for building file hierarchies. Format: UUID.

Get SAS URL for file upload › Responses

Success response

blobPath

string · required

Blob path within the organization's storage container.

expiresAt

string · required

Expiration time of the upload URL. ISO timestamp. Example: 2026-03-31T15:55:41.222Z.

fileId

string · required

The ID of the created file record, in a pending state until upload completes. Format: UUID. Example: 70326069-1786-01c4-4653-066594021234.

message

string · required

Human-readable response message.

success

boolean · required

Whether the request was successful.

uploadUrl

string · required

The SAS URL for uploading the file content via a PUT request. Valid for 15 minutes; include the x-ms-blob-type: BlockBlob header when uploading.

POST/files

curl https://platform.bevaya.ai/api/v1/files \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "filename": "document.pdf",
  "workspaceId": "2b8d1514-6231-5c79-9108-5110495d6789",
  "category": "DOCUMENT_PROCESSING"
}'

Example Request Body

{
  "filename": "document.pdf",
  "workspaceId": "2b8d1514-6231-5c79-9108-5110495d6789",
  "category": "DOCUMENT_PROCESSING"
}

json

application/json

Example Responses

{
  "success": true,
  "message": "Upload URL generated",
  "fileId": "70326069-1786-01c4-4653-066594021234",
  "uploadUrl": "https://blobs.bevaya.ai/1d7c0403-5120-4b68-8097-4009384c5678/uploads/70326069-1786-01c4-4653-066594021234?sv=2024-08-04&se=2026-03-31T16%3A10%3A00Z&sr=b&sp=cw&sig=example",
  "blobPath": "uploads/70326069-1786-01c4-4653-066594021234",
  "expiresAt": "2026-03-31T15:55:41.222Z"
}

json

application/json

Get file metadata and download URL

GET

https://platform.bevaya.ai/api/v1

/files/{fileId}

Retrieve file details and a presigned download URL.

Get file metadata and download URL › path Parameters

fileId

string · required · style: simple

Get file metadata and download URL › Responses

Success response

dto.FileResponseDto · required

message

string · required

Human-readable result message.

success

boolean · required

Whether the file was found and returned successfully.

Get file pages

GET

https://platform.bevaya.ai/api/v1

/files/{fileId}/pages

Retrieve paginated image renderings of each page in a file (e.g. a PDF).

Get file pages › path Parameters

fileId

string · required · style: simple

Get file pages › query Parameters

documentId

string · style: form · explode: true

Optional document ID to filter pages to a single document within the file. Format: UUID.

Get file pages › Responses

Success response

message

string · required

Human-readable result message.

dto.PageDto[] · required

The requested page of results.

success

boolean · required

Whether the pages were found and returned successfully.

totalCount

number · required

Total number of pages available for the file (or document, if filtered).

Authentication Flow Executions

Get SAS URL for file upload

POST

https://platform.bevaya.ai/api/v1

/files

The returned URL is valid for 15 minutes (write SAS token).

Get SAS URL for file upload › Request Body

filename

string · required

Name of the file with extension. Required for validation and MIME type detection. Example: document.pdf.

workspaceId

string · required

The workspace to associate the uploaded file with. Format: UUID. Example: 2b8d1514-6231-5c79-9108-5110495d6789.

category

client.FileCategory · enum

Enum values:

KNOWLEDGE

CONTEXT

HELPER

DOCUMENT_PROCESSING

itemId

string

Optional item ID to associate the file with. Format: UUID. Example: 6f215958-0675-90b3-3542-955483910123.

parentFileId

string

Optional parent file ID, for building file hierarchies. Format: UUID.

Get SAS URL for file upload › Responses

Success response

blobPath

string · required

Blob path within the organization's storage container.

expiresAt

string · required

Expiration time of the upload URL. ISO timestamp. Example: 2026-03-31T15:55:41.222Z.

fileId

string · required

The ID of the created file record, in a pending state until upload completes. Format: UUID. Example: 70326069-1786-01c4-4653-066594021234.

message

string · required

Human-readable response message.

success

boolean · required

Whether the request was successful.

uploadUrl

string · required

The SAS URL for uploading the file content via a PUT request. Valid for 15 minutes; include the x-ms-blob-type: BlockBlob header when uploading.

Get file metadata and download URL

GET

https://platform.bevaya.ai/api/v1

/files/{fileId}

Retrieve file details and a presigned download URL.

Get file metadata and download URL › path Parameters

fileId

string · required · style: simple

Get file metadata and download URL › Responses

Success response

dto.FileResponseDto · required

message

string · required

Human-readable result message.

success

boolean · required

Whether the file was found and returned successfully.

Get file pages

GET

https://platform.bevaya.ai/api/v1

/files/{fileId}/pages

Retrieve paginated image renderings of each page in a file (e.g. a PDF).

Get file pages › path Parameters

fileId

string · required · style: simple

Get file pages › query Parameters

documentId

string · style: form · explode: true

Optional document ID to filter pages to a single document within the file. Format: UUID.

Get file pages › Responses

Success response

message

string · required

Human-readable result message.

dto.PageDto[] · required

The requested page of results.

success

boolean · required

Whether the pages were found and returned successfully.

totalCount

number · required

Total number of pages available for the file (or document, if filtered).