Manage Agent Files

Upload, list, and delete files from an agent's knowledge base. Files are indexed for retrieval-augmented generation (RAG), allowing the agent to reference uploaded documents when answering questions.

List Agent Files

Retrieve all files associated with an agent.

Endpoint

GET /api/v1/agents/files/{agentId}

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent

Success Response

Status Code: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "file-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "content_type": "document",
      "file_name": "product-catalog.pdf",
      "file_type": "pdf",
      "file_url": null,
      "source": "api",
      "created_at": "2024-01-20T14:30:00Z"
    }
  ],
  "count": 1
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
data	array	Array of file context records
data[].id	string	Unique identifier for the file record
data[].agent_id	string	ID of the agent this file belongs to
data[].content_type	string	Type of content (e.g., document)
data[].file_name	string	Original filename
data[].file_type	string	File extension (e.g., pdf, docx, txt)
data[].file_url	string | null	URL to the stored file
data[].source	string	Upload source (api, web)
data[].created_at	string (ISO 8601)	When the file was uploaded
count	number	Total number of files

---

Upload Files

Upload one or more files to an agent's knowledge base. Files are automatically indexed in both Gemini and OpenAI vector stores for RAG capabilities.

Endpoint

POST /api/v1/agents/files/{agentId}

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent

Headers

Header	Type	Required	Description
Authorization	string	Yes	Your API key in the format Bearer pk_xxx:sk_xxx
Content-Type	string	Yes	Must be multipart/form-data

Form Fields

Field	Type	Required	Description
file	File	Yes	The file(s) to upload. Multiple files supported
description	string	No	Description for the file (one per file)

Success Response

Status Code: 201 Created

{
  "success": true,
  "results": [
    {
      "filename": "product-catalog.pdf",
      "status": "uploaded-indexed",
      "gemini": {
        "storeName": "corpora/agent-store-123",
        "success": true
      },
      "openai": {
        "vectorStoreId": "vs_abc123",
        "fileId": "file-xyz789",
        "success": true
      },
      "file_url": null,
      "row_id": "file-001"
    }
  ],
  "geminiStoreName": "corpora/agent-store-123",
  "openaiAssistantId": "asst_abc123",
  "openaiVectorStoreId": "vs_abc123"
}

Response Fields

Field	Type	Description
success	boolean	Overall success status
results	array	Per-file upload results
results[].filename	string	Original filename
results[].status	string	uploaded-indexed (indexed in vector store), uploaded (stored but not indexed), or failed
results[].gemini	object	Gemini indexing result
results[].openai	object	OpenAI indexing result
results[].file_url	string | null	URL to the stored file
results[].row_id	string	Database record ID
geminiStoreName	string | null	Gemini store identifier
openaiAssistantId	string	OpenAI assistant ID
openaiVectorStoreId	string	OpenAI vector store ID

Supported File Types

• PDF documents (.pdf)
• Word documents (.docx)
• Text files (.txt)
• CSV files (.csv) - auto-converted to text
• Excel spreadsheets (.xlsx, .xls) - auto-converted to text

---

Delete a File

Remove a file from an agent's knowledge base.

Endpoint

DELETE /api/v1/agents/files/{agentId}?fileId={fileId}

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent

Query Parameters

Parameter	Type	Required	Description
fileId	string	Yes	The ID of the file record to delete

Success Response

Status Code: 200 OK

{
  "success": true,
  "message": "File file-001 deleted successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "fileId query parameter is required"
}

404 Not Found

{
  "success": false,
  "error": "File not found"
}

---

Authentication

All file management endpoints require API key authentication:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Example Usage

Upload a File (cURL)

curl -X POST https://agentsgt.com/api/v1/agents/files/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890" \
  -F "file=@./product-catalog.pdf" \
  -F "description=Product catalog with pricing and specifications"

Upload Multiple Files (cURL)

curl -X POST https://agentsgt.com/api/v1/agents/files/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890" \
  -F "file=@./catalog.pdf" \
  -F "description=Product catalog" \
  -F "file=@./faq.txt" \
  -F "description=Frequently asked questions"

List Files (JavaScript)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://agentsgt.com/api/v1/agents/files/${agentId}`,
  {
    headers: {
      'Authorization': `Bearer ${publicKey}:${secretKey}`
    }
  }
);

const data = await response.json();
console.log(`${data.count} files found`);
data.data.forEach(file => {
  console.log(`- ${file.file_name} (${file.file_type})`);
});

Upload a File (Python)

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}'
}

files = {
    'file': ('catalog.pdf', open('catalog.pdf', 'rb'), 'application/pdf')
}

data = {
    'description': 'Product catalog with pricing'
}

response = requests.post(
    f'https://agentsgt.com/api/v1/agents/files/{agent_id}',
    headers=headers,
    files=files,
    data=data
)

if response.status_code == 201:
    result = response.json()
    for file_result in result['results']:
        print(f"{file_result['filename']}: {file_result['status']}")

Delete a File (cURL)

curl -X DELETE "https://agentsgt.com/api/v1/agents/files/550e8400-e29b-41d4-a716-446655440000?fileId=file-001" \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890"

Notes

• Uploaded files are indexed in both Gemini and OpenAI vector stores for maximum retrieval capability
• Excel and CSV files are automatically converted to text format before indexing
• The first file upload for an agent creates the vector stores and OpenAI assistant automatically
• Subsequent uploads reuse the existing vector stores
• File metadata is stored in the agent_context database table
• Deleting a file removes the database record but may not immediately remove it from external vector stores

Related Endpoints

• Get Agent Details - Get agent configuration
• Send Message - Send a message (agent can reference uploaded files)
• Get All Agents - List all agents