Knowledge API Reference

Base URL: https://api.universalapi.co

All endpoints require authentication.

List Files

GET /knowledge/list?prefix={folder}

# List root
curl -s https://api.universalapi.co/knowledge/list \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

# List a folder
curl -s "https://api.universalapi.co/knowledge/list?prefix=documents" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Upload File (Direct)

POST /knowledge/upload

Upload a file directly in a single API call — no presigned URL needed. This is the preferred method for AI agents and programmatic uploads.

Max size: 5 MB. For larger files, use Get Upload URL instead.

# Upload a text file
curl -s -X POST https://api.universalapi.co/knowledge/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "notes.md",
    "content": "# My Notes\n\nHello from the API!",
    "contentType": "text/markdown",
    "folder": "documents"
  }' | jq

Request body:

Field	Type	Required	Description
fileName	string	✅	File name (e.g., notes.md, data.csv)
content	string	✅	File content as text, or base64-encoded for binary
contentType	string		MIME type (default: text/plain)
folder	string		Target folder (omit for root)
isBase64	boolean		Set true if content is base64-encoded

Response:

{
  "data": {
    "key": "users/{userId}/documents/notes.md",
    "fileName": "notes.md",
    "size": 32,
    "storageUsedMb": 7.41,
    "storageQuotaMb": 100
  }
}

TIP

Files uploaded via this endpoint are automatically indexed for semantic search, just like presigned URL uploads.

Get Upload URL

POST /knowledge/upload-url

curl -s -X POST https://api.universalapi.co/knowledge/upload-url \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "report.pdf",
    "contentType": "application/pdf",
    "folder": "documents"
  }' | jq

Returns a presigned PUT URL valid for 1 hour. Upload the file with:

curl -X PUT -H "Content-Type: application/pdf" \
  --data-binary @report.pdf "PRESIGNED_URL"

Get Download URL

POST /knowledge/download-url

curl -s -X POST https://api.universalapi.co/knowledge/download-url \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "users/xxx/documents/report.pdf"}' | jq

The key comes from the list response.

Delete File

ANY /knowledge/delete

curl -s -X POST https://api.universalapi.co/knowledge/delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "users/xxx/documents/report.pdf"}' | jq

Create Folder

POST /knowledge/create-folder

curl -s -X POST https://api.universalapi.co/knowledge/create-folder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderName": "documents", "parentFolder": ""}' | jq

Delete Folder

POST /knowledge/delete-folder

curl -s -X POST https://api.universalapi.co/knowledge/delete-folder \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "users/xxx/documents/"}' | jq

DANGER

Deleting a folder removes all files inside it. This cannot be undone.

Semantic Search

POST /knowledge/search

curl -s -X POST https://api.universalapi.co/knowledge/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue figures",
    "folder": "reports",
    "limit": 5
  }' | jq

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
folder	string	No	Restrict to a folder
fileType	string	No	Filter by extension (pdf, txt, md)
limit	number	No	Max results (default: 5, max: 20)