Files

Initiate a chunked upload

Start a multipart upload session for a large file. Validates the file type, size, and destination up front, then returns an upload_id. Send the file in parts with PUT /files/uploads/{upload_id}/parts/{part_number}, then finalize with POST /files/uploads/{upload_id}/complete.

Use this instead of POST /files when a single request is impractical (large files, or clients with per-request payload limits). The destination options (folder_id / project_id / scope) behave exactly as on POST /files.

post/files/uploads

Request

Base URL
https://app.gc.ai/api/external/v1
Auth
API key in header Authorization
TypeScript
https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/files/uploads/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

file_namestring required

Original filename, including extension.

content_typestring

MIME type of the file. When omitted, it is derived from the filename extension.

sizeinteger required

Total size of the complete file in bytes. Validated up front against the file-size limit so oversized uploads fail before any parts are sent.

folder_idstring uuid

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

project_idstring 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'my-files' | 'organization'

Upload to the root of a meta-collection ("my-files" or "organization"). Mutually exclusive with folder_id and project_id. User-scoped keys only.

Example request

{
  "file_name": "msa-2026.pdf",
  "content_type": "application/pdf",
  "size": 12582912,
  "scope": "my-files"
}

Response

Upload session created

upload_idstring uuid required

Opaque identifier for this upload session. Use it in the part and complete requests.

part_sizenumber required

Recommended part size in bytes. Split the file into parts no larger than this for reliable transfers.

max_partsnumber required

Maximum number of parts allowed for this session. Part numbers run from 1 to this value.

expires_atstring required

ISO 8601 timestamp after which the session expires. Upload all parts and call complete before this.

Changes

No recorded changes to this operation across all 1 revision of this API.