> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.alfa.boosted.ai/alfa/guides/build-with-alfa/knowledge-base/documents/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server. # Documents > Learn how to upload, manage, and use documents with Alfa workflows Documents allow you to analyze your own data using Alfa workplans. This guide explains how to upload documents, list them, and reference them in your workplan prompts. ## Uploading documents You can upload your own documents (PDFs, Word files, Excel spreadsheets, etc.) to be processed and made available to your workplans. ```python import requests BASE_URL = "https://alfa.boosted.ai/client" API_KEY = "YOUR_API_KEY_HERE" headers = {"x-api-key": API_KEY} # No Content-Type for multipart uploads def upload_documents(file_paths): """ Upload one or more documents for use with workplans. Args: file_paths (list): List of paths to files you want to upload Returns: dict: Response with uploaded document details """ url = f"{BASE_URL}/v2/documents/add-documents" # Prepare files for multipart upload files = [] for path in file_paths: file_name = path.split("/")[-1] files.append(("files", (file_name, open(path, "rb")))) # Make the request without Content-Type header (it's set automatically) response = requests.post( url, headers={"x-api-key": API_KEY}, files=files ) # Close all file handles for _, (_, file_obj) in files: file_obj.close() if response.status_code == 202: return response.json() else: print(f"Error uploading documents: {response.status_code}, {response.text}") return None # Example usage file_paths = [ "/path/to/quarterly_report.pdf", "/path/to/market_analysis.docx" ] upload_result = upload_documents(file_paths) if upload_result and upload_result.get("success"): print(f"Successfully uploaded {len(upload_result.get('added_listings', []))} documents") for doc in upload_result.get("added_listings", []): print(f"Document ID: {doc['file_id']}") print(f"Name: {doc['name']}") print(f"Size: {doc['size']} bytes") print("---") ``` ### Example: Uploading quarterly reports #### Prepare your documents Gather the documents you want to analyze (PDFs, Excel files, Word documents, etc.) #### Upload the documents ```python # Upload Q1 and Q2 reports to a designated folder quarterly_reports = [ "Q1_2023_Financials.pdf", "Q2_2023_Financials.pdf" ] result = upload_documents(quarterly_reports) # Store document IDs for later use document_ids = {} if result and result.get("success"): for doc in result.get("added_listings", []): document_ids[doc["name"]] = doc["file_id"] print(f"Uploaded: {doc['name']} (ID: {doc['file_id']})") ``` > **Tip** > > For large documents, the upload process may take some time as the system processes and indexes the content for searching. ## Listing documents To view all documents that you've uploaded: ```python def list_documents(): """ List all documents in your workspace. Returns: list: List of document objects with their details """ url = f"{BASE_URL}/v2/documents/list_documents" response = requests.get(url, headers=headers) if response.status_code == 200: data = response.json() return data.get("documents", []) else: print(f"Error listing documents: {response.status_code}, {response.text}") return [] # Get and display all documents documents = list_documents() print(f"Found {len(documents)} documents:") for doc in documents: print(f"ID: {doc['file_id']}") print(f"Name: {doc['name']}") print(f"Type: {doc['type']}") print(f"Upload time: {doc['upload_time']}") print("---") ``` ## Creating workplans with documents You can reference documents in your workplan prompts using a special syntax. The workplan will then be able to read and analyze these documents. ```python def create_workplan_with_document(prompt, document_id): """ Create an workplan that references a document. Args: prompt (str): The prompt with {doc} placeholder document_id (str): The ID of the document to reference Returns: str: The workplan ID if successful, empty string otherwise """ url = f"{BASE_URL}/v2/workplans/create # Create the request payload with the document reference payload = { "prompt": prompt, "args": { "doc": { "id": document_id, "type": "custom_document" } } } response = requests.post(url, headers=headers, json=payload) if response.status_code == 201: data = response.json() workplan_id = data.get("workplan_id") print(f"workplan created with ID: {workplan_id}") return workplan_id else: print(f"Error creating workplan: {response.status_code}, {response.text}") return "" # Example: Create an workplan to analyze a quarterly report document_id = "6fcc0ae7-809b-498c-b35b-4ced1114438b" # ID from a previous upload prompt = "Read the document {doc} and summarize its key points. Format the summary to be easy to read." workplan_id = create_workplan_with_document(prompt, document_id) ``` > **Note** > > The `{doc}` placeholder in your prompt will be replaced with the actual document content when the workplan processes it. ### Understanding the document reference format The payload for creating an workplan with a document reference follows this structure: ```json { "prompt": "Read the document {doc} and summarize its key points. Format the summary to be easy to read.", "args": { "doc": { "id": "6fcc0ae7-809b-498c-b35b-4ced1114438b", "type": "custom_document" } } } ``` * **prompt**: Your instruction with the `{doc}` placeholder * **args**: A dictionary mapping placeholders to their values * **doc**: The placeholder name that matches what you used in the prompt * **id**: The unique ID of the document (obtained when uploading or listing documents) * **type**: Must be "custom\_document" to indicate you're referencing a document > Learn how to upload, manage, and use documents with Alfa workflows