Sources API

Manage data sources and RAG search.

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/sources	List sources
POST	/api/agents/{id}/sources	Create source
GET	/api/agents/{id}/sources/search	Search sources
GET	/api/agents/{id}/sources/{sourceId}	Get source
DELETE	/api/agents/{id}/sources/{sourceId}	Delete source

List Sources

GET /api/agents/{id}/sources

Response

{
  "sources": [
    {
      "id": "source-123",
      "type": "file",
      "name": "Product Manual",
      "status": "ready",
      "chunks": 150,
      "created_at": "2024-12-01T00:00:00Z"
    }
  ]
}

Create Source

File Upload

POST /api/agents/{id}/sources
Content-Type: multipart/form-data

-F "type=file"
-F "name=Product Manual"
-F "file=@/path/to/manual.pdf"

URL Source

POST /api/agents/{id}/sources
Content-Type: application/json

{
  "type": "url",
  "name": "Documentation",
  "url": "https://docs.example.com",
  "config": {
    "depth": 2,
    "max_pages": 100
  }
}

Response

{
  "id": "source-123",
  "type": "file",
  "name": "Product Manual",
  "status": "processing",
  "created_at": "2024-12-15T10:00:00Z"
}

Search Sources

GET /api/agents/{id}/sources/search?query=how+to+reset+password&limit=5

Query Parameters

Parameter	Type	Description
query	string	Search query (required)
limit	number	Max results (default: 10)
source_id	string	Filter by source
min_score	number	Minimum similarity score

Response

{
  "results": [
    {
      "id": "chunk-123",
      "source_id": "source-456",
      "content": "To reset your password, go to Settings > Account > Password...",
      "score": 0.92,
      "metadata": {
        "source_name": "User Guide",
        "page": 15,
        "section": "Account Settings"
      }
    }
  ]
}

Get Source

GET /api/agents/{id}/sources/{sourceId}

Response

{
  "id": "source-123",
  "type": "file",
  "name": "Product Manual",
  "file_path": "uploads/manual.pdf",
  "status": "ready",
  "chunks": 150,
  "config": {
    "chunk_size": 1000,
    "overlap": 200
  },
  "created_at": "2024-12-01T00:00:00Z",
  "updated_at": "2024-12-15T10:00:00Z"
}

Delete Source

DELETE /api/agents/{id}/sources/{sourceId}

Response

{
  "success": true
}

Refresh Source

POST /api/agents/{id}/sources/{sourceId}/refresh

Reprocesses the source content.

Source Types

Type	Description
file	Uploaded file
url	Web page/site
database	Database query
api	API endpoint

Source Status

Status	Description
pending	Waiting to process
processing	Currently processing
ready	Available for search
error	Processing failed
updating	Refreshing content

Supported Formats

Format	Extensions
PDF	.pdf
Text	.txt
Markdown	.md
Word	.docx
JSON	.json
CSV	.csv

Chunking Config

{
  "config": {
    "chunk_size": 1000,
    "overlap": 200,
    "method": "semantic"
  }
}

Errors

Code	Description
400	Invalid source data
404	Source not found
413	File too large
415	Unsupported format

Examples

Upload PDF

curl -X POST .../sources \
  -F "type=file" \
  -F "name=User Guide" \
  -F "file=@guide.pdf"

Search with Filter

curl ".../sources/search?query=installation&source_id=source-123&min_score=0.8"

Crawl Website

curl -X POST .../sources \
  -d '{
    "type": "url",
    "name": "Help Center",
    "url": "https://help.example.com",
    "config": {
      "depth": 3,
      "max_pages": 500
    }
  }'