> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.eyelevel.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eyelevel.ai/_mcp/server.

# Ingesting Documents

For direct API calls, choose an ingest method:

#### [ingest_remote](/reference/api-reference/documents/ingest-documents/ingest-remote)

Ingest documents from public URLs or supported private-upload URLs into a GroundX bucket.

#### [ingest_local](/reference/api-reference/documents/ingest-documents/ingest-local)

Upload local files into a GroundX bucket.

The [supported SDKs](/sdks/ground-x-sd-ks) provide an **`ingest`** method for local and remote documents.

## Ingest

**`documents`** `array` — required

An array of [Document](#document) objects.

---

**`wait_for_complete`** `bool`

Waits until ingest completes when true. Default is false.

---

**`batch_size`** `int`

Files per ingest request, from 1 to 50. Default is 10.

---

**`upload_api`** `str`

An endpoint that returns a presigned upload URL in the JSON key `URL`. Default is the EyeLevel.ai file upload endpoint.

---

**`callback_url`** `str`

An endpoint that receives processing updates through POST requests.

---

**`callback_data`** `str`

A string included in processing updates sent to the callback URL.

---

## Document

**`bucketId`** `integer` — required

The ID of the destination bucket.

---

**`filePath`** `string` — required

The document's local file path or remote URL.

---

**`fileName`** `string`

The file's display name.

---

**`fileType`** `enum`

A supported document type.

---

**`filter`** `object`

Key-value metadata used to restrict which documents a search can return.

---

**`processLevel`** `enum`

The processing level for document chunks. Default is `full`.

---

**`searchData`** `object`

Custom metadata used to improve search ranking.

---

#### ingest

**`Python`**

```python title="Python"
from groundx import Document, GroundX

client = GroundX(
  api_key="YOUR_API_KEY",
)
client.ingest(
  documents=[
    Document(
      bucket_id=1234,
      file_name="my_file1.txt",
      file_path="https://my.source.url.com/file1.txt",
      file_type="txt",
    ),
    Document(
      bucket_id=1234,
      file_name="my_file2.pdf",
      file_path="/local/path/file2.pdf",
      file_type="pdf",
      filter={
        permissions = {
          roles = ["moderator","admin"]
        },
        # other metadata that can be used for pre-filtering of documents prior to search
      },
      search_data=dict(
        key = "value",
      ),
    )
  ],
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { GroundXClient } from "groundx";

const client = new GroundXClient({ apiKey: "YOUR_API_KEY" });
await client.ingest(
  [
    {
      bucketId: 1234,
      fileName: "my_file1.txt",
      filePath: "https://my.source.url.com/file1.txt",
      fileType: "txt",
    },
    {
      bucketId: 1234,
      fileName: "my_file2.pdf",
      filePath: "/local/path/file2.pdf",
      fileType: "pdf",
      searchData: {
        "key": "val",
      },
    }
  ]
);
```

## Private sources and initial policies

On compatible deployments, remote ingest accepts public source URLs and private-upload `hostedUrl` values owned by your account. Each local, remote or crawl item can set an initial `fileAccess` policy without a revision. Omitted or null policies inherit account or bucket settings. Use private upload before sending protected files, including protected files in public buckets. See [File Access and Sharing](/documentation/fundamentals/file-access-and-sharing) for upload steps, per-file policies and inherited limits.