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

# Ingesting Documents

If you are using the APIs directly, choose from one of the following methods.

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

Ingest documents hosted on public URLs into a GroundX bucket.

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

Upload documents hosted on a local file system into a GroundX bucket.

If you are using one of the [supported SDKs](/sdks/ground-x-sd-ks), the **`ingest`** method can be used to ingest both local and remote documents.

## Ingest

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

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

---

**`wait_for_complete`** `bool`

A flag that will block until the ingest process is complete. Default is false.

---

**`batch_size`** `int`

The size of each batch ingest request. Default is 10. Min is 1 and Max is 50.

---

**`upload_api`** `str`

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

---

**`callback_url`** `str`

An endpoint that will receive processing event updates as POST.

---

**`callback_data`** `str`

A string that is returned, along with processing event updates, to the callback URL.

---

## Document

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

The bucketId of the bucket which this file will be ingested to.

---

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

The local file path or remote URL of the document being ingested by GroundX.

---

**`fileName`** `string`

The name of the file being ingested.

---

**`fileType`** `enum`

The type of document (one of the currently supported file types).

---

**`filter`** `object`

A dictionary of key-value pairs that can be used to pre-filter documents prior to a search.

---

**`processLevel`** `enum`

The amount of processing to perform on chunks (default 'full').

---

**`searchData`** `object`

Custom metadata which can be used to influence GroundX’s search functionality. This data can be used to further hone GroundX search.

---

#### 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",
      },
    }
  ]
);
```


## API Docs

- Ingest Documents [ingest - Local Documents](https://docs.eyelevel.ai/reference/api-reference/documents/ingest-documents/ingest-local.md)
- Ingest Documents [ingest - Remote Documents](https://docs.eyelevel.ai/reference/api-reference/documents/ingest-documents/ingest-remote.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.eyelevel.ai/reference/api-reference/documents/ingest-documents/openapi.json)
- [OpenAPI YAML](https://docs.eyelevel.ai/reference/api-reference/documents/ingest-documents/openapi.yaml)