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

# Upload file

> Upload a file the user has attached into GC AI.

<Info>
  **Tool** `upload_file` · **Behavior** Open world
</Info>

Upload a file the user has attached into GC AI. To upload, just call this tool: the host populates the `file` argument automatically. Do not read or pass a local/sandbox path (e.g. /mnt/data/...) and do not construct `file.download_url` yourself. The bytes are fetched, stored, and processed (text extraction + embeddings) in place. Poll readiness with `get_files({ id })` until `status` is "ready" (then use the file) or "failed" (then `extraction_error` explains why). Target the upload with `project_id` (into a project) or `scope` ("my-files" / "organization"); the two are mutually exclusive and default to "my-files".

## Input parameters

<ParamField body="file" type="object" required>
  The file to upload. The host populates this automatically when the user attaches a file. Do not construct it or pass a local/sandbox path (e.g. /mnt/data/...); just call the tool and let the host attach the file reference.

  <Expandable title="properties">
    <ParamField body="download_url" type="string (uri)" required>
      Temporary URL to download the file bytes from.
    </ParamField>

    <ParamField body="file_id" type="string" required>
      Stable identifier for the file from the client.
    </ParamField>

    <ParamField body="mime_type" type="string">
      MIME type of the file, if known.
    </ParamField>

    <ParamField body="file_name" type="string">
      Original filename, if known.
    </ParamField>
  </Expandable>
</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="id" type="string (uuid)" />

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

<ResponseField name="size" type="number" />

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

<ResponseField name="status" type="'ready' | 'extracting' | 'embedding' | 'failed'" />

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

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

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

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

<ResponseField name="hint" type="string">
  Plain-language next step: use the file immediately when ready, poll get\_files while still processing, or stop on failure.
</ResponseField>