> ## 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.

# Sources API

> Manage indexed sources

# Sources API

Create, read, update, and delete sources.

## Create Source

<ParamField body="name" type="string" required>
  Human-readable name for the source
</ParamField>

<ParamField body="source_type" type="string" required>
  Source type: `repo`, `docs`, or `pdf` (PDFs can also be created via `POST /sources/upload`)
</ParamField>

<ParamField body="url" type="string" required>
  Git URL for repos, base URL or spec URL for docs
</ParamField>

<ParamField body="branch" type="string">
  Git branch (repos only, default: `main`)
</ParamField>

<ParamField body="docs_format" type="string">
  Docs format: `html` or `openapi` (default: `html`)
</ParamField>

<ParamField body="doc_urls" type="string[]">
  Explicit URL list for HTML docs
</ParamField>

<ParamField body="use_sitemap" type="boolean">
  Use sitemap for URL discovery (HTML docs only)
</ParamField>

<ParamField body="include_patterns" type="string[]">
  Glob patterns to include
</ParamField>

<ParamField body="exclude_patterns" type="string[]">
  Glob patterns to exclude
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.trygroundai.com/sources \
    -H "Authorization: Bearer gnd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My API",
      "source_type": "docs",
      "docs_format": "openapi",
      "url": "https://api.example.com/openapi.json"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My API",
    "source_type": "docs",
    "status": "pending",
    "url": "https://api.example.com/openapi.json",
    "docs_format": "openapi",
    "file_count": 0,
    "chunk_count": 0,
    "created_at": "2026-01-17T10:00:00Z",
    "updated_at": "2026-01-17T10:00:00Z"
  }
  ```
</ResponseExample>

## List Sources

<RequestExample>
  ```bash theme={null}
  curl "https://api.trygroundai.com/sources?skip=0&limit=50"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "sources": [
      {
        "id": "...",
        "name": "My API",
        "source_type": "docs",
        "status": "synced",
        "url": "https://api.example.com/openapi.json",
        "docs_format": "openapi",
        "file_count": 45,
        "chunk_count": 45,
        "last_sync_completed": "2026-01-17T10:05:00Z",
        "created_at": "2026-01-17T10:00:00Z",
        "updated_at": "2026-01-17T10:05:00Z"
      }
    ],
    "total": 1
  }
  ```
</ResponseExample>

## Get Source

<RequestExample>
  ```bash theme={null}
  curl https://api.trygroundai.com/sources/{source_id} \
    -H "Authorization: Bearer gnd_your_api_key"
  ```
</RequestExample>

## Update Source

<RequestExample>
  ```bash theme={null}
  curl -X PATCH https://api.trygroundai.com/sources/{source_id} \
    -H "Authorization: Bearer gnd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Name",
      "include_patterns": ["*.py"]
    }'
  ```
</RequestExample>

## Delete Source

Deletes the source and all its indexed content.

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://api.trygroundai.com/sources/{source_id} \
    -H "Authorization: Bearer gnd_your_api_key"
  ```
</RequestExample>

## Trigger Sync

Starts a background job to sync the source.

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.trygroundai.com/sources/{source_id}/sync \
    -H "Authorization: Bearer gnd_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "job_id": "job-uuid",
    "source_id": "source-uuid",
    "message": "Sync job started"
  }
  ```
</ResponseExample>

Returns `409 Conflict` if a sync is already running for this source.

## Upload PDF (multipart)

Creates a `pdf` source from an uploaded file and queues ingestion.

```
POST /sources/upload
```

Form fields:

* **`file`**: PDF binary (`multipart/form-data`)
* **`name`**: Display name for the source

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.trygroundai.com/sources/upload \
    -H "Authorization: Bearer gnd_your_api_key" \
    -F "file=@./spec.pdf" \
    -F "name=Product spec"
  ```
</RequestExample>