API Overview

Ground exposes a REST API for indexing sources, searching (hybrid and RMH), agent chat, Rover GitHub jobs, on-demand package search, API keys, and usage visibility.

Base URL

https://api.trygroundai.com

Authentication

Create keys in the dashboard. Send your key using either:

Authorization: Bearer gnd_your_api_key, or
X-API-Key: gnd_your_api_key

curl -H "Authorization: Bearer gnd_your_api_key" https://api.trygroundai.com/sources

Some browser-only flows (for example the dashboard) use JWT cookies; automation and SDKs should use API keys as above.

Endpoints (summary)

Sources

Method	Endpoint	Description
`POST`	`/sources`	Create a source
`POST`	`/sources/upload`	Upload a PDF as a `pdf` source (multipart)
`GET`	`/sources`	List sources
`GET`	`/sources/{id}`	Get a source
`PATCH`	`/sources/{id}`	Update a source
`DELETE`	`/sources/{id}`	Delete a source
`POST`	`/sources/{id}/sync`	Trigger sync

Jobs

Method	Endpoint	Description
`GET`	`/jobs`	List jobs
`GET`	`/jobs/{id}`	Get job status
`POST`	`/jobs/{id}/cancel`	Cancel a job

Search

Method	Endpoint	Description
`GET`	`/search`	Hybrid search (query params)
`POST`	`/search`	Hybrid search (JSON body)
`POST`	`/search/rmh`	RMH (recursive multi-hop) search

Package search (on-demand)

Method	Endpoint	Description
`GET`	`/packages/search`	Search public npm/PyPI source
`POST`	`/packages/search`	Same as GET with JSON body

Chat

Method	Endpoint	Description
`POST`	`/chat`	Agent answer with citations
`POST`	`/chat/stream`	Same flow, SSE token stream
`POST`	`/chat/upload-pdf`	Ephemeral PDF for chat context (multipart)

Dashboard chat also uses JWT-backed /conversations for history; see product UI or OpenAPI for details.

Rover

Method	Endpoint	Description
`POST`	`/rover/jobs`	Create Rover job
`GET`	`/rover/jobs`	List jobs
`GET`	`/rover/jobs/{id}`	Get job
`GET`	`/rover/jobs/{id}/stream`	SSE progress
`DELETE`	`/rover/jobs/{id}`	Cancel pending / running

Global packages

Method	Endpoint	Description
`GET`	`/packages/global`	Public catalog
`GET`	`/packages/global/{id}`	Public package detail
`POST`	`/packages/add`	Link package to tenant (starts sync)
`GET`	`/packages/my-packages`	List tenant links
`DELETE`	`/packages/my-packages/{link_id}`	Remove link

API keys & quota

Method	Endpoint	Description
`POST`	`/keys`	Create API key
`GET`	`/keys`	List keys
`DELETE`	`/keys/{key_id}`	Revoke key
`GET`	`/quota`	View limit configuration
`GET`	`/quota/usage`	View current usage

Policy

Method	Endpoint	Description
`GET`	`/policy`	Get retrieval policy
`PUT`	`/policy`	Update policy
`POST`	`/policy/reset`	Reset to defaults

Common response codes

Code	Description
`200`	Success
`201`	Created
`204`	No content
`400`	Bad request
`401`	Unauthorized
`404`	Not found
`409`	Conflict
`429`	Rate limited
`500`	Server error

Pagination & filters

List endpoints support skip / limit or documented equivalents. Example:

curl "https://api.trygroundai.com/sources?skip=0&limit=50" \
  -H "Authorization: Bearer gnd_your_api_key"

Support

Documentation: docs.trygroundai.com · ali@trygroundai.com

​API Overview

​Base URL

​Authentication

​Endpoints (summary)

​Sources

​Jobs

​Search

​Package search (on-demand)

​Chat

​Rover

​Global packages

​API keys & quota

​Policy

​Common response codes

​Pagination & filters

​Support