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

<Note>
  The MCP server is in public beta. It is open to use and still being refined, so tools and behavior may change.
</Note>

<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), `vault_id` (as a document in a Contract Intelligence vault), or `scope` ("my-files" / "organization"); the three 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 `vault_id` and `scope`.
</ParamField>

<ParamField body="vault_id" type="string (uuid)">
  Add the file as a document in this Contract Intelligence vault, so it gets scanned against the vault's columns. Requires the editor or owner role in the vault, and the vault accepts PDF, Word, and text files only. Find the id with `get_vaults`. Mutually exclusive with `project_id` and `scope`.
</ParamField>

<ParamField body="scope" type="'my-files' | 'organization'">
  Upload to the root of "my-files" or "organization". Mutually exclusive with `project_id` and `vault_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="vault_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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.