# Knowledge Sources

List knowledge sources and their processing status.

---

Knowledge sources are the documents, URLs, and files you've loaded to train your agent. Programming guides, AS-built drawings, manufacturer spec sheets, commissioning checklists, internal SOPs. This endpoint lets you check their processing status and metadata.

> **Note:** Internal file paths (storage locations) are never exposed through this endpoint. Only public-facing metadata is returned.

## List knowledge sources

```
GET /api/v1/apps/{appId}/knowledge-sources
```

Returns a paginated list of knowledge sources. Uses offset-based pagination.

### Query parameters

| Parameter  | Type     | Default | Description                       |
|------------|----------|---------|-----------------------------------|
| `limit`    | integer  | 25      | Results per page (1-100).         |
| `offset`   | integer  | 0       | Number of results to skip.        |
| `status`   | string   | -       | Filter by processing status.      |
| `type`     | string   | -       | Filter by source type.            |

**Status values:** `pending`, `processing`, `completed`, `failed`, `deleting`.

**Type values:** `file`, `url`, `google_drive`, `notion`, `text`, `qa`, `sitemap`, `youtube`, `confluence`.

### Example

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/knowledge-sources?status=completed" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "ks-001",
      "name": "Crestron 4-Series Programming Guide",
      "type": "file",
      "status": "completed",
      "url": null,
      "error_message": null,
      "chunk_count": 1,
      "file_size_bytes": 24576,
      "refresh_interval_hours": null,
      "last_refreshed_at": null,
      "created_at": "2025-05-10T08:00:00Z",
      "updated_at": "2025-05-10T08:02:30Z"
    },
    {
      "id": "ks-002",
      "name": "Manufacturer Firmware Notes",
      "type": "url",
      "status": "completed",
      "url": "https://example.com/firmware",
      "error_message": null,
      "chunk_count": 24,
      "file_size_bytes": null,
      "refresh_interval_hours": 168,
      "last_refreshed_at": "2025-06-01T06:00:00Z",
      "created_at": "2025-05-12T14:00:00Z",
      "updated_at": "2025-06-01T06:00:00Z"
    },
    {
      "id": "ks-003",
      "name": "Q-SYS Lua Module Library Docs",
      "type": "url",
      "status": "processing",
      "url": "https://docs.example.com",
      "error_message": null,
      "chunk_count": 0,
      "file_size_bytes": null,
      "refresh_interval_hours": null,
      "last_refreshed_at": null,
      "created_at": "2025-06-15T12:00:00Z",
      "updated_at": "2025-06-15T12:00:05Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "total": 3,
    "limit": 25,
    "offset": 0
  }
}
```

### Response fields

| Field                    | Type             | Description                                                                                           |
|--------------------------|------------------|-------------------------------------------------------------------------------------------------------|
| `id`                     | string           | Unique knowledge source identifier.                                                                   |
| `name`                   | string           | Display name.                                                                                         |
| `type`                   | string           | Source type: `file`, `url`, `google_drive`, `notion`, `text`, `qa`, `sitemap`, `youtube`, `confluence`. |
| `status`                 | string           | Processing status: `pending`, `processing`, `completed`, `failed`, or `deleting`.                     |
| `url`                    | string or null   | Source URL, if applicable.                                                                            |
| `error_message`          | string or null   | Error details if the source failed processing.                                                        |
| `chunk_count`            | integer          | Number of chunks extracted.                                                                           |
| `file_size_bytes`        | integer or null  | File size in bytes.                                                                                   |
| `refresh_interval_hours` | integer or null  | Auto-refresh interval in hours.                                                                       |
| `last_refreshed_at`      | ISO 8601 or null | When the source was last refreshed.                                                                   |
| `created_at`             | ISO 8601         | When the source was added.                                                                            |
| `updated_at`             | ISO 8601         | When the source was last updated.                                                                     |

### Checking for failed sources

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/knowledge-sources?status=failed" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

*AVCodex · Your AV expertise. Amplified by AI.*