Ingesting Documents | Documentation

For direct API calls, choose an ingest method:

ingest_remote

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

ingest_local

Upload local files into a GroundX bucket.

The supported SDKs provide an ingest method for local and remote documents.

Ingest

documents

arrayRequired

An array of 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. See Receiving callbacks.

callback_data

str

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

Document

bucketId

integerRequired

The ID of the destination bucket.

filePath

stringRequired

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.

Receiving callbacks

GroundX does not sign or authenticate callbacks, so any server that knows your callback URL can send requests to it. Treat a callback as a notice that a process changed, not as proof. To confirm the result, call GET /v1/ingest/{processId} with your own API key, using the processId from the callback. See get_processing_status_by_id.

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 for upload steps, per-file policies and inherited limits.