> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygroundai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Ground REST API — sources, search, RMH, chat, Rover, packages, keys, and quota.

# 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](https://app.trygroundai.com). Send your key using **either**:

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

```bash theme={null}
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:

```bash theme={null}
curl "https://api.trygroundai.com/sources?skip=0&limit=50" \
  -H "Authorization: Bearer gnd_your_api_key"
```

## Support

Documentation: [docs.trygroundai.com](https://docs.trygroundai.com) · [ali@trygroundai.com](mailto:ali@trygroundai.com)