File Support in Custom Integrations

1. When to Use File Inputs

Retrieve files from (custom) integrated tools to use them directly in Langdock
Upload files to a (custom) integrated tool or external API

2. Adding File Fields to an Action

2. 1 Single‑File Input

Add an input field to the action of type file to allow accessing uploaded files later in the action code.

2.2 Multi‑File Input

For multiple file input, select Allow multiple files. Screenshot 2025-07-22 at 19.30.43.png

3. Reading File Data in Code

Every uploaded or referenced file is delivered in a FileData object:

{
  fileName: "Invoice.pdf",
  mimeType: "application/pdf",
  size: 102400,          // bytes
  base64: "JVBERi0xLjQK...", // binary content, Base64‑encoded
  /* Optional shortcut for plain‑text files */
  text: "Hello world"
}

3.1  Single File

const doc = data.input.document;        // FileData
const buffer = Buffer.from(doc.base64, "base64");
ld.log(`Processing ${doc.fileName} (${doc.size} bytes)…`);

3.2  Multiple Files

for (const file of data.input.attachments) {
  const buf = Buffer.from(file.base64, "base64");
  await process(buf, file.mimeType);
}

Shortcut for text files For small UTF‑8 files you may skip Base64 entirely:
{
  fileName: "notes.txt",
  mimeType: "text/plain",
  text: "Hello world"
}

3.3 Common Patterns

Show Document Processing

const pdf = data.input.document;
const pdfBuf = Buffer.from(pdf.base64, "base64");
const info   = await parsePdf(pdfBuf);

return {
  success: true,
  pages:   info.pageCount,
  message: `Parsed ${info.pageCount} pages from ${pdf.fileName}`,
};

Show Image Analysis

const image = data.input.image;
if (image.mimeType.startsWith("image/")) {
  const imageBuffer = Buffer.from(image.base64, "base64");

  // Process image
  const analysis = await analyzeImage(imageBuffer);

  return {
    success: true,
    result: {
      filename: image.fileName,
      dimensions: analysis.dimensions,
      format: analysis.format,
    },
  };
}

Show Batch convert many files

const files = data.input.files;
const results = [];

for (const file of files) {
  try {
    const fileBuffer = Buffer.from(file.base64, "base64");
    const result = await processFile(fileBuffer, file.mimeType);

    results.push({
      filename: file.fileName,
      status: "success",
      result: result,
    });
  } catch (error) {
    results.push({
      filename: file.fileName,
      status: "error",
      error: error.message,
    });
  }
}

return {
  success: true,
  processed: results.length,
  results: results,
};

Show Send File to External API

const document = data.input.document;

try {
  const response = await ld.request({
    method: "POST",
    url: "https://api.example.com/process-document",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${data.auth.api_key}`,
    },
    body: {
      filename: document.fileName,
      base64: document.base64,
      mimeType: document.mimeType,
    },
  });

  if (response.status === 200) {
    return {
      success: true,
      result: response.json,
    };
  } else {
    throw new Error(`API returned status ${response.status}`);
  }
} catch (error) {
  ld.log("Error processing document:", error.message);
  return {
    success: false,
    error: `Failed to process ${document.fileName}: ${error.message}`,
  };
}

4. Returning Files from actions

Building file output from actions is similar to building native download actions.

{
  fileName: "Report.pdf", 		// Original filename
  mimeType: "application/pdf",	// MIME type
  size: 1024000,				// File size in bytes
  base64: "base64EncodedData",	// Base64 encoded file content
}

Field	Required	Notes
`fileName`	✓	Include extension
`mimeType`	✓	Accurate type controls preview icons & parsing
`size`	✓	File size in bytes
`text` / `base64`	✓*	Provide one of them, never both
`url`	✓	Opens the file in the source app
`lastModified`	✓	ISO‑8601 or `Date`
`data`	–	Raw API response for debugging

5. Platform Constraints

The following constraints have to be considered when implementing actions handling file uploads or retrieval.

Limit	Value
Total file size per action run	100 MB
Individual documents (single file)	≤ 256 MB*
Individual images	≤ 20 MB
Individual spreadsheets	≤ 30 MB
Individual audio files	≤ 200 MB*
Processing Timeout	Action execution timeout of 2 minutes applies to file processing

*Still bounded by the 100 MB overall cap.

Exceeding a limit throws a validation error before your code runs.

{
  "error": "Total file size (120.0 MB) exceeds the action execution limit of 100.0 MB. Please use smaller files or reduce the number of files."
}

6. Best Practices

Stream large files if possible; avoid loading >50 MB into memory.
Process files in parallel when generating multiple files.
Log progress (ld.log("Processing 3/10 files")) to help debugging.

7. Troubleshooting Checklist

Symptom/Error	Likely Cause & Fix
“File not found”	User forgot to attach a file Make file input field required
Size‑limit error	File(s) > 100 MB → request smaller batch
File upload/download fails	Ensure content is properly base64 encoded Check logs for file processing errors

The following snippet illustrates a compact logging block that captures the essential metadata without exposing the file contents:

// Quick debug helper
ld.log({
  fileName: file.fileName,
  mimeType: file.mimeType,
  size: file.size,
  hasText: !!file.text,
});

Prompt Engineering

Guides

Other resources

File Support in Custom Integrations

1. When to Use File Inputs

2. Adding File Fields to an Action

2. 1 Single‑File Input

2.2 Multi‑File Input

3. Reading File Data in Code

3.1  Single File

3.2  Multiple Files

3.3 Common Patterns

4. Returning Files from actions

5. Platform Constraints

6. Best Practices

7. Troubleshooting Checklist

Prompt Engineering

Guides

Other resources

​1. When to Use File Inputs

​2. Adding File Fields to an Action

​2. 1 Single‑File Input

​2.2 Multi‑File Input

​3. Reading File Data in Code

​3.1 Single File

​3.2 Multiple Files

​3.3 Common Patterns

​4. Returning Files from actions

​5. Platform Constraints

​6. Best Practices

​7. Troubleshooting Checklist

1. When to Use File Inputs

2. Adding File Fields to an Action

2. 1 Single‑File Input

2.2 Multi‑File Input

3. Reading File Data in Code

3.1  Single File

3.2  Multiple Files

3.3 Common Patterns

4. Returning Files from actions

5. Platform Constraints

6. Best Practices

7. Troubleshooting Checklist