---
title: "Initiate a chunked upload"
method: POST
path: "/files/uploads"
tags: ["Files"]
---

# Initiate a chunked upload

`POST /files/uploads`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/files/uploads`
- 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)

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`.

## Request body

- InitiateUploadRequest
  - `file_name` string, required: Original filename, including extension.
  - `content_type` string: MIME type of the file. When omitted, it is derived from the filename extension.
  - `size` integer, 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_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` '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.

## Response `200`

Upload session created

- InitiateUploadResponse
  - `upload_id` string, uuid, required: Opaque identifier for this upload session. Use it in the part and complete requests.
  - `part_size` number, required: Recommended part size in bytes. Split the file into parts no larger than this for reliable transfers.
  - `max_parts` number, required: Maximum number of parts allowed for this session. Part numbers run from 1 to this value.
  - `expires_at` string, required: ISO 8601 timestamp after which the session expires. Upload all parts and call complete before this.

## Other responses

- `400`: Invalid request (unsupported file type, size over the limit, conflicting destination options)
- `401`: Missing or malformed API key
- `403`: Project access required
- `404`: Folder or project not found
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)