API Concepts

This page introduces some of the key concepts that form the foundation of GroundX’s suite of APIs and services. Understanding these concepts will help you make the most of our APIs.

Ingest

GroundX’s Ingest API provides a powerful tool for uploading your content, supporting a variety of data types and formats. You can upload entire websites via a URL, documents, presentations, and raw text files. The API is designed to ensure secure transmission and centralized storage of your content, simplifying content management.

There are four ways to upload content GroundX via API:

• Ingest Local: uploads individual files from your local filesystem.
• Ingest Remote: uploads individual files hosted on a remote URL.
• Ingest Directories: Implemented in the PythonSDK, this automatically crawls a directory structure and batch uploads files. This is particularly convenient when uploading large amounts of files as it automatically manages batch uploading.
• Crawl Website: Crawls a website recursively and uploads the html to GroundX.

X-Ray

A document X-Ray is the summarized GroundX understanding of your documents. It is the end result of the GroundX Ingest API and contains document, section, and chunk layout and metadata information. This information is stored in the GroundX search database and can be accessed using the GroundX Search API. You can also download the X-Ray data and use it outside of GroundX Search in your own internal systems.

Buckets

Buckets are a core feature of the GroundX APIs, aimed at the effective organization and storage of content. When documents or other forms of content are uploaded to the GroundX pipeline, they are processed and then stored in buckets. Buckets are the unit of search: every search call targets a single bucket, a group of buckets, or an explicit list of documents. Bucket-internal organization (folders, tenants, access tiers, and similar) is best modeled with each document’s filter metadata rather than by creating additional buckets.

Groups

Groups in GroundX consolidate a small number of buckets so they can be searched together in a single call. When using the search APIs, you can pass a groupId to search.content and the search runs across every bucket in the group. Groups are the right tool when a small number of distinct content corpora need to be queried at once. For best search quality, keep a group to roughly 1–4 buckets — the candidate budget the reranker operates on is divided across member buckets, so larger groups give the reranker fewer candidates per bucket.

For organizing content within a single bucket — for example by project, folder, tenant, or access tier — use the filter field on each document instead of splitting content across many buckets and groups.

Workflows

Workflows control how documents are processed during ingest — chunking strategy, section strategy, custom LLM steps, and extract agent definitions. A workflow can be assigned to the account (used as the default for every ingest), to a specific bucket or group (which overrides the account default for files ingested into that scope), or implicitly per-document via the processLevel field on the ingest call. More specific assignments override broader ones. The Workflows API exposes CRUD over workflow definitions and add_to_account / add_to_id operations to manage assignments.

Search

GroundX’s Search API implements a proprietary combined vector and semantic approach, offering a level of search precision and relevance that is superior to traditional methods. The API allows for real-time application of pre-processors to better understand and match queries to relevant content.

Authentication

To ensure secure access to its services, GroundX uses API Key based authentication. The API Key is provided to the users upon completion of a request form and is used in the request header (X-API-Key) for authentication.

GroundX On-Prem

GroundX On-Prem allows you to leverage the power of GroundX within hardened and secure environments without any external dependencies, meaning it can be used in air-gapped environments.

If you want to leverage the power of GroundX in your security conscious environment, check out the GroundX On-Prem GitHub repo