Skip to main content
POST
Upload a file

Authorizations

Authorization
string
header
required

API key for authentication. Format: gcai_xxxxxxxxx

Create API keys in the GC AI app under Settings → API.

Body

multipart/form-data
file
file
required

The file to upload

folder_id
string<uuid>

Target folder ID. Defaults to the user's "My Files" folder. Mutually exclusive with project_id and scope.

project_id
string<uuid>

Upload the file into a project. The file is placed in the project's upload folder and linked to the project. Mutually exclusive with folder_id and scope.

scope
enum<string>

Upload to the root of a meta-collection ("my-files" or "organization"). Mutually exclusive with folder_id and project_id. shared-with-me is not valid for upload.

Available options:
my-files,
organization
Example:

"my-files"

Response

File uploaded successfully

id
string<uuid>
required

Unique file identifier

name
string
required

Original filename

size
number
required

File size in bytes

content_type
string
required

MIME type of the file

Example:

"application/pdf"

status
enum<string>
required

Current processing status of the file

Available options:
extracting,
embedding,
ready,
failed
created_at
string
required

ISO 8601 creation timestamp

folder_id
string<uuid> | null

Folder the file belongs to

extraction_error
string

Error message if extraction failed

project_id
string<uuid>

Project the file is linked to, if uploaded with project_id

warning
string

Present when the file was uploaded successfully but a secondary operation (e.g. project linking) failed