groundx-api

GroundX API Skill

Use this skill for customer-scoped GroundX platform operations: ingest, processing status, search, document lookup, source retrieval, buckets, groups, workflows, extraction retrieval, SDK integration, and REST fallback.

Routing Contract

• Role: reference.
• First-entry intents: GroundX customer API behavior, document ingest, semantic search, RAG with citations, workflows, buckets, groups, documents, account health, and API keys.
• Deferrals: schema-first extraction YAML and field-accuracy iteration start in groundx-extraction-workflows; deployment and values.yaml work starts in groundx-on-prem; architecture-shaped questions start in groundx-architecture.
• Before producing output: read references/01-auth.md, then the operation reference or guide matching the endpoint being used.
• Misuse cases: do not put secret keys in browser code, examples, docs, logs, or generated artifacts; do not invent endpoint shapes from memory.

Agent Flow

1. Classify the request: API operation, schema-first extraction, deployment, or architecture.
2. Read references/01-auth.md.
3. Try GroundX MCP tools first. If visible, call groundx_account_context, prefer the matching MCP tool, and use REST only when the required tool is not exposed.
4. If GroundX MCP tools are not visible, instruct the user to connect the GroundX API connector and retry discovery before REST fallback.
5. Read the smallest operation reference and guide that matches the work.
6. Keep secrets server-side and encode async operations, pagination, errors, and URL versioning into code defaults and tests.

Common Implementation Paths

User needs...	Read after auth
Upload files and make them searchable	references/02-documents.md, references/08-errors-and-limits.md, guides/02-ingest-patterns.md
Grounded chat or RAG with citations	references/03-search.md, guides/03-search.md, guides/04-rag-integration-patterns.md
Source viewer or page-level citation UI	guides/08-source-view-ui.md, then references/03-search.md
Content organized by tenant, project, folder, or access policy	guides/06-content-organization.md, guides/07-filter-field.md, then bucket/group references
Workflow CRUD or workflow-backed document processing	references/06-workflows.md, guides/09-workflows.md, then references/02-documents.md
Python SDK code	references/12-python-sdk-objects.md before writing objects or attributes

Reference Map

Use references/README.md as the fast task-to-reference index. Before producing anything API-related, read references/01-auth.md, then only the operation-specific reference and guide the task needs.

Pre-return Checklist

• REST calls use X-API-Key, never Authorization: Bearer.
• GroundX MCP is attempted before REST; if tools are missing, the user was told to connect the GroundX API connector before REST fallback.
• Raw API keys do not appear in MCP tool arguments, logs, transcripts, browser code, examples, or generated files.
• REST URLs avoid double-version paths such as /api/v1/v1/....
• Async operations that return a processId include polling guidance.
• Pagination uses nextToken where list results may be truncated.