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
Authentication
Create keys in the dashboard. Send your key using either:Authorization: Bearer gnd_your_api_key, orX-API-Key: gnd_your_api_key
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) |
/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 supportskip / limit or documented equivalents. Example: