Skip to navigation
Fundamentals

API Concepts

GroundX ingests documents, organizes them into buckets and returns search results with document context.

Ingest

The Ingest API uploads and processes documents, presentations, text files and website content.

There are four ways to upload content to GroundX:

  • Ingest Local: uploads individual files from your local filesystem.
  • Ingest Remote: uploads individual files hosted on a remote URL.
  • Ingest Directories: uses the Python SDK to find files in a directory tree and upload them in batches.
  • Crawl Website: follows website links and uploads the HTML to GroundX.

Semantic Objects

GroundX identifies paragraphs, tables and figures, then converts them into text with document and section context. These units are called Semantic Objects. GroundX stores them in buckets and returns them in search results.

X-Ray

X-Ray contains GroundX’s analysis of a document, including layout and metadata for its sections and chunks. It is stored as a separate file, outside the search database. Retrieve it through GET /v1/ingest/document/xray/{documentId} or download it for use in your own systems.

Buckets

Buckets organize processed documents. Every search targets a bucket, a group of buckets or a list of documents. Use each document’s filter metadata to organize content within a bucket by folder, tenant or access tier.

Groups

Groups let you search several buckets in one call. Pass a groupId to search.content to search every bucket in the group. Keep groups to roughly 1 to 4 buckets for best search quality. The reranker considers a limited number of candidate results, divided among the buckets; larger groups leave fewer candidates per bucket.

To organize content within a bucket by project, folder, tenant or access tier, use the filter field on each document instead of splitting content across many buckets and groups.

Older GroundX documentation referred to this concept as “Projects” and exposed a projectId. The current API uses groupId and group_* operations throughout; projectId is no longer a parameter on any endpoint.

Workflows

Workflows control chunking, sections, custom LLM steps and extraction during ingest. An account workflow provides the default for all ingests. Bucket or group assignments override that default, while an ingest’s processLevel selects processing for the individual document. More specific assignments take precedence. The Workflows API creates, reads, updates and deletes definitions; add_to_account and add_to_id manage assignments.

When updating a workflow, include every custom setting you want to keep. Omitted settings return to GroundX defaults. For example, send a step’s engine object and omit prompt to customize its LLM endpoint while keeping the default prompt. Omit a step to restore its defaults; send null only to disable or clear it. Include custom processing settings even when changing only the name. On deployments without this update behavior, supply explicit prompt objects for steps that must not become empty.

Search first combines keyword and vector matching against chunk metadata in OpenSearch. A fine-tuned reranker then scores the candidates for semantic similarity. GroundX combines both scores to rank the results.

Authentication

GroundX REST APIs authenticate with an API key in the X-API-Key header. Customer-tier REST authentication does not provide role-based access control or single sign-on.

GroundX On-Prem

GroundX On-Prem runs in private and air-gapped environments without external dependencies. It supports Kubernetes distributions including Red Hat OpenShift. Compliance certifications or attestations, such as FedRAMP or GDPR, are the deployer’s responsibility; GroundX does not hold them on the deployer’s behalf.

For deployment details, see the GroundX On-Prem GitHub repo

Agent Harness

GroundX Agent Harness is a plugin for an agent runtime (Claude, Codex, or another supported client). It provides instructions, reference material and workflows for ingest, search and extraction. See What Is GroundX Agent Harness? for the full overview.

MCP

MCP (Model Context Protocol) lets connected agents call authenticated GroundX tools. The Agent Harness plugin supplies instructions. To call GroundX, connect through authenticated MCP or use an API key with the SDK or REST API. See Connect Hosted MCP Tools for setup and available tools.

File policy scope

Documents inherit bucket settings, and buckets inherit account settings. File URLs are public and do not expire by default. Protected stable URLs require authentication on every read. Recipient share links expire. Set initial policies during creation or ingest without a revision; later changes require the resource’s current revision. See File Access and Sharing for private uploads and deployment requirements.