File API

This API provides endpoints for File Support. You can upload files, list them, retrieve file details, delete them, and access their content

Refer to the API Reference for generic variables needed to use the API.

Endpoints

Authentication

All endpoints require authentication using one of the following:

• Authorization: Bearer $GLOBAI_APITOKEN
• Authorization: Bearer $OAuth_accesstoken
• Authorization: Bearer $GLOBAI_ORGANIZATION_APITOKEN

POST /files

Uploads a file to the system.

Request

• Method: POST
• Path: $BASE_URL/v1/files
• Headers:
  • Authorization: See Authentication section above.
  • Accept: application/json
  • fileName: Specify file name (needed information).
  • organizationId: $ORGANIZATION_ID.
  • projectId: Project ID.
  • project-id: Alternative single header that can be used instead of both organizationId and projectId.
  • folder: Destination folder (optional). If not provided, the file will be temporarily saved.

Response

{
    "dataFileId": "string", 
    "dataFileUrl": "string",
    "success": true
}

cURL Sample

curl -X POST "$BASE_URL/v1/files" 
  -H "Authorization: Bearer $GEAI_APITOKEN" 
  -H "Accept: application/json"
  -H "fileName: $FILE_NAME"
  -H "organizationId: $ORGANIZATION_ID"
  -H "projectId: $PROJECT_ID"
  -H "folder: $FOLDER"
  -F "file=@/path/to/file.txt"  // The file you want to upload.

curl -X POST "$BASE_URL/v1/files" 
  -H "Authorization: Bearer $GEAI_APITOKEN"
  -H "Accept: application/json"
  -H "fileName: $FILE_NAME"            
  -H "project-id: $PROJECT_ID" //               alternative single header with no need to indicate organizationId
  -H "folder: $FOLDER"
  -F "file=@/path/to/file.txt"  // The file you want to upload.

GET /files/{fileId}

Gets a file by Id.

This endpoint requires $GEAI_ORGANIZATION_APITOKEN. If you use the $OAuth_accesstoken you will only see the files you uploaded.

Parameters

Request

• Method: GET
• Path: $BASE_URL/v1/files/{fileId}
• Headers:
  • Authorization: See Authentication section above.
  • Accept: application/json

Response

{
    "dataFileExtension": "string",
    "dataFileId": "string",
    "dataFileName": "string",
    "dataFilePurpose": "string"
    "dataFileSize": numeric,
    "dataFileUrl": "string",
    "organizationId": "string",
    "projectId": "string",
    "success": true
}

cURL Sample

curl -X GET "$BASE_URL/v1/files/{fileId}" 
  -H "Authorization: Bearer $GEAI_APITOKEN" 
  -H "Accept: application/json"
  -G 
  -d "organization=$ORGANIZATION_ID" 
  -d "project=$PROJECT_ID" 

DELETE /files/{fileId}

Deletes a file by Id.

This endpoint requires a $GEAI_ORGANIZATION_APITOKEN.

Parameters

Request

• Method: DELETE
• Path: $BASE_URL/v1/files/{fileId}
• Headers:
  • Authorization: See Authentication section above.
  • Accept: application/json

Response

{
    "success": true
}

cURL Sample

curl -X DELETE "$BASE_URL/v1/files/{fileId}"
  -H "Authorization: Bearer $GEAI_APITOKEN"
  -H "Accept: application/json"
  -G
  -d "organization=$ORGANIZATION_ID"
  -d "project=$PROJECT_ID" 

GET /files/{fileId}/content

Retrieves the content of a file by Id.

This endpoint requires $GEAI_ORGANIZATION_APITOKEN. If you use the $OAuth_accesstoken you will only see the files you uploaded.

Parameters

Request

• Method: GET
• Path: $BASE_URL/v1/files/{fileId}/content
• Headers:
  • Authorization: BearerToken $GEAI_APITOKEN.
  • Accept: application/json

Response

{
    "content": "string"
  }

cURL Sample

curl -X GET "$BASE_URL/v1/files/{fileId}/content" 
  -H "Authorization: Bearer $GEAI_APITOKEN" 
  -H "Accept: application/json"
  -G 
  -d "organization=$ORGANIZATION_ID" 
  -d "project=$PROJECT_ID" 

GET /files/all

Gets all files.

This endpoint requires $GEAI_ORGANIZATION_APITOKEN. If you use the $OAuth_accesstoken you will only see the files you uploaded.

Request

• Method: GET
• Path: $BASE_URL/v1/files/all
• Headers:
  • Authorization: See Authentication section above.
  • Accept: application/json

Response

{
  "dataFiles": 
    {
      "DataFileExtension": "string",
      "DataFileId": "string",
      "DataFileName": "string",
      "DataFilePurpose": "string",
      "DataFileSize": "number",
      "DataFileUrl": "string"
    },
    {
      "DataFileExtension": "string",
      "DataFileId": "string",
      "DataFileName": "string",
      "DataFilePurpose": "string",
      "DataFileSize": "number",
      "DataFileUrl": "string"
    }
  
}

cURL Sample

curl -X GET "$BASE_URL/v1/files/all" 
  -H "Authorization: Bearer $GEAI_APITOKEN" 
  -H "Accept: application/json"
  -G 
  -d "organization=$ORGANIZATION_ID" 
  -d "project=$PROJECT_ID" 

GET v1/file-security/file/{fileId}/secureUrl

Downloads a file securely by Id. Introduces a centralized secure file access mechanism through the FileSecurityAPI, validating permissions and returning files directly on each request and centralizing cross-functional file security features such as secure access and antivirus scanning.

This endpoint supports three authentication methods: $GEAI_APITOKEN, $OAuth_accesstoken and access from Browser with an active $OAuth session. In this scenario, the endpoint detects the browser User-Agent header and automatically resolves authentication through $OAuth.

Request

• Method: GET
• Path: $BASE_URL/v1/file-security/file/{fileId}/secureUrl
• Body: empty

Response

The response returns the file content directly as binary data. Depending on the file type and client used, the response may be rendered as an image preview, downloaded file, or binary stream.

cURL Sample

curl --location '$BASE_URL/v1/file-security/file/{fileId}/secureUrl' \
--header 'organization: {organizationId}' \
--header 'project: {projectId}' \
--header 'Authorization: Bearer $GEAI_APITOKEN'

curl --location '$BASE_URL/v1/file-security/file/{fileId}/secureUrl' \
--header 'organization: {organizationId}' \
--header 'project: {projectId}' \
--header 'Authorization: Bearer $OAuth_Accesstoken'

GET /files/byName/{fileName}/metadata

Retrieves a file’s metadata by its filename within the specified organization and project. Returns metadata only; file content is not included.

Request

• Method: GET
• Path: $BASE_URL/v1/files/byName/{fileName}/metadata
• Body: empty

Response

{
  "dataFileExtension": "string",            // File extension (e.g., "pdf", "txt")
  "dataFileId": "string",                   // Unique identifier of the file (UUID)
  "dataFileName": "string",                 // Original file name
  "dataFilePurpose": "string",              // Purpose or classification (e.g., "Assistant")
  "dataFileSize": integer,                        // File size in bytes (integer)
  "dataFileUrl": "string",                  // Relative URL/path to the file within the project scope
  "organizationId": "string",               // Organization identifier
  "projectId": "string",                    // Project identifier
  "success": boolean                           // Indicates if the metadata was found and returned (boolean)
}

cURL Sample

curl --location "$BASE_URL/v1/files/byName/prospect.pdf/metadata?organization=$GLOBAI_ORGANIZATION_ID&project=$GLOBAI_PROJECT_ID" \
  -H "Authorization: Bearer $GLOBAI_APITOKEN" \
  -H "Accept: application/json"

See Also

How to upload and manage Files via API