Upload File

Upload a file directly to create a knowledge item. This endpoint handles file uploads using multipart/form-data and automatically processes the file into searchable knowledge.

Endpoint

POST /v1/workspaces/{workspaceId}/knowledge/file

Authentication

Requires Bearer token authentication. See Authentication for details.

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace

Request Body

This endpoint uses multipart/form-data encoding to handle file uploads.

FieldTypeRequiredDescription
fileFileYesThe file to upload (binary data)
titlestringNoOptional title for the knowledge item
descriptionstringNoOptional description for the knowledge item
languagestringNoOptional language code (e.g., 'en', 'es', 'fr')
statusstringNoProcessing mode: BACKGROUND_START for async. Default: synchronous

Supported File Types

Documents

  • application/pdf - PDF documents
  • application/msword - Word documents (.doc)
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word documents (.docx)
  • text/plain - Text files
  • text/markdown - Markdown files

Spreadsheets

  • application/vnd.ms-excel - Excel files (.xls)
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - Excel files (.xlsx)
  • text/csv - CSV files

Images

  • image/jpeg - JPEG images
  • image/png - PNG images
  • image/gif - GIF images
  • image/webp - WebP images

Media

  • video/mp4 - MP4 videos
  • audio/mpeg - MP3 audio
  • audio/wav - WAV audio

Archives

  • application/zip - ZIP archives
  • application/x-zip-compressed - ZIP archives (alternate)

Data

  • application/json - JSON files

Response

Success Response

Status Code: 201 Created

Headers:

X-API-Version: v1

Body:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "knowledgeId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Product Documentation",
  "type": "FILE",
  "status": "PROCESSED"
}
FieldTypeDescription
idstring (UUID)Unique identifier for the created knowledge item
knowledgeIdstring (UUID)Same as id, provided for compatibility
titlestringTitle of the knowledge item
typestringAlways FILE for uploaded files
statusstringProcessing status: PROCESSED, PROCESSING, or BACKGROUND_START

Upload Workflow

This endpoint provides a simple, single-step file upload process using multipart/form-data.

Direct Upload (Single Request)

Upload a file and create the knowledge item in one request:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/file' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/product-documentation.pdf' \
  -F 'title=Product Documentation' \
  -F 'status=BACKGROUND_START'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "knowledgeId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Product Documentation",
  "type": "FILE",
  "status": "PROCESSING"
}

With Description and Language

Include optional description and language with your upload:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/file' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/document.pdf' \
  -F 'title=Technical Specification' \
  -F 'description=Complete technical specification for version 2.0' \
  -F 'language=en' \
  -F 'status=BACKGROUND_START'

Complete Example

Here's a complete example in different languages:

cURL

# Upload a file and create knowledge item
curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/knowledge/file' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./document.pdf' \
  -F 'title=My Document' \
  -F 'description=Documentation for my project' \
  -F 'language=en' \
  -F 'status=BACKGROUND_START'

JavaScript/TypeScript

const API_KEY = 'YOUR_API_KEY';
const WORKSPACE_ID = 'your-workspace-id';
const BASE_URL = 'https://api.sharely.ai/v1';
 
async function uploadFile(file, options = {}) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('title', options.title || file.name);
 
  if (options.description) {
    formData.append('description', options.description);
  }
 
  if (options.language) {
    formData.append('language', options.language);
  }
 
  formData.append('status', 'BACKGROUND_START');
 
  const response = await fetch(
    `${BASE_URL}/workspaces/${WORKSPACE_ID}/knowledge/file`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      },
      body: formData
    }
  );
 
  if (!response.ok) {
    throw new Error(`Upload failed: ${response.statusText}`);
  }
 
  return await response.json();
}
 
// Usage
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
 
const result = await uploadFile(file, {
  title: 'My Document',
  description: 'Documentation for my project',
  language: 'en'
});
 
console.log('Knowledge created:', result.id);

Python

import requests
import json
 
API_KEY = 'YOUR_API_KEY'
WORKSPACE_ID = 'your-workspace-id'
BASE_URL = 'https://api.sharely.ai/v1'
 
def upload_file(file_path, title=None, description=None, language=None):
    # Prepare the multipart form data
    files = {
        'file': open(file_path, 'rb')
    }
 
    data = {
        'title': title or file_path.split('/')[-1],
        'status': 'BACKGROUND_START'
    }
 
    if description:
        data['description'] = description
 
    if language:
        data['language'] = language
 
    # Upload the file
    response = requests.post(
        f'{BASE_URL}/workspaces/{WORKSPACE_ID}/knowledge/file',
        headers={'Authorization': f'Bearer {API_KEY}'},
        files=files,
        data=data
    )
 
    response.raise_for_status()
    return response.json()
 
# Usage
result = upload_file(
    './document.pdf',
    title='My Document',
    description='Documentation for my project',
    language='en'
)
print(f"Knowledge created: {result['id']}")

Error Responses

400 Bad Request

Missing or invalid request parameters:

{
  "error": "Bad Request",
  "message": "Missing required field: fileName"
}

Or unsupported file type:

{
  "error": "Bad Request",
  "message": "Unsupported file type"
}

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Insufficient permissions or storage quota exceeded:

{
  "error": "Forbidden",
  "message": "Storage quota exceeded"
}

500 Internal Server Error

Failed to generate signed URL:

{
  "error": "Internal Server Error",
  "message": "Failed to generate upload URL"
}

Best Practices

Use Async Processing for Large Files

  • For files larger than 10MB, set status: "BACKGROUND_START"
  • This prevents timeout errors during processing
  • Poll the knowledge status to check processing completion

Set Clear Titles

  • Always provide a descriptive title
  • If omitted, the filename will be used
  • Clear titles improve searchability

Include Description and Language

  • Add descriptions for better context and searchability
  • Specify the language code for multilingual content
  • Use clear, concise descriptions that explain the document's purpose

Error Handling

try {
  const response = await uploadFile(file);
  console.log('Upload successful:', response.id);
} catch (error) {
  if (error.status === 403) {
    console.error('Storage quota exceeded');
  } else if (error.status === 400) {
    console.error('Invalid file type or parameters');
  } else if (error.status === 413) {
    console.error('File too large');
  } else {
    console.error('Upload failed:', error.message);
  }
}

Check File Size Limits

  • Verify file size before upload
  • Check your workspace plan for limits
  • Split large documents if necessary

Notes

Direct Upload

  • This endpoint provides a single-step upload process
  • Files are uploaded using multipart/form-data
  • Processing begins immediately after upload completes

File Size Limits

  • Check your workspace plan for file size limits
  • Free tier: Up to 10MB per file
  • Pro tier: Up to 50MB per file
  • Enterprise plans support larger files
  • Contact support for custom limits

Processing Time

  • Small files (< 10MB): Typically under 1 minute
  • Medium files (10-50MB): 1-5 minutes
  • Large files (> 50MB): 5+ minutes
  • Use status: "BACKGROUND_START" for async processing

Content Extraction

  • PDFs: Text and embedded images are extracted
  • Office docs: Full content extraction with formatting preserved
  • Images: OCR is applied to extract text
  • Archives: Contents are extracted and processed individually

Related Endpoints