> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start file upload

> Start uploading a file that only exists in your local/sandbox filesystem (use this when no host-attached file reference is available, e.g. on Claude).

<Info>
  **Tool** `start_file_upload` · **Behavior** Additive
</Info>

Start uploading a file that only exists in your local/sandbox filesystem (use this when no host-attached file reference is available, e.g. on Claude). Returns a short-lived signed `upload_url`: PUT the file bytes straight to it from your sandbox, for example `curl -X PUT --upload-file <path> "<upload_url>"`. Then call `finish_file_upload` with the returned `file_id` to register and process the file. Target with `project_id` or `scope` (mutually exclusive, default "my-files"). If the host already populates a file reference, prefer `upload_file` instead.

## Input parameters

<ParamField body="file_name" type="string" required>
  Original filename, including extension (e.g. "contract.pdf").
</ParamField>

<ParamField body="mime_type" type="string">
  MIME type, if known. Inferred from the filename when omitted.
</ParamField>

<ParamField body="project_id" type="string (uuid)">
  Upload into a project you can edit. Mutually exclusive with `scope`.
</ParamField>

<ParamField body="scope" type="'my-files' | 'organization'">
  Upload to the root of "my-files" or "organization". Mutually exclusive with `project_id`. Defaults to "my-files".
</ParamField>

## Response

<ResponseField name="file_id" type="string (uuid)" />

<ResponseField name="upload_url" type="string" />

<ResponseField name="expires_at" type="string" />