Password-Protected Files

Extend supports processing password-protected PDF files. You can provide the file’s password directly in your API request so that Extend can unlock and process the document.

Providing a Password via URL

When providing a file by URL (in parse, extract, classify, split, edit, or workflow runs), include the password in the settings object on the file input:

1{
2  "file": {
3    "url": "https://example.com/protected.pdf",
4    "name": "protected.pdf",
5    "settings": {
6      "password": "your-file-password"
7    }
8  }
9}
1const response = await fetch("https://api.extend.ai/parse", {
2  method: "POST",
3  headers: {
4    Authorization: "Bearer <API_TOKEN>",
5    "Content-Type": "application/json",
6    "x-extend-api-version": "2026-02-09",
7  },
8  body: JSON.stringify({
9    file: {
10      url: "https://example.com/protected.pdf",
11      name: "protected.pdf",
12      settings: {
13        password: "your-file-password",
14      },
15    },
16    config: {
17      target: "markdown",
18    },
19  }),
20});
21
22const data = await response.json();

The settings object is available on URL-based file inputs across all run endpoints:

EndpointSupports settings.password
POST /parse / POST /parse_runs✅
POST /extract / POST /extract_runs✅
POST /classify / POST /classify_runs✅
POST /split / POST /split_runs✅
POST /edit / POST /edit_runs✅
Workflow runs✅

Password is only applicable to URL-based file inputs. When referencing a previously uploaded file by id, the file was already uploaded (and optionally password-unlocked) at upload time.

Providing a Password When Uploading a File

When uploading a file via POST /files/upload, include the password as a password field in the multipart/form-data request:

1const fs = require("fs");
2const FormData = require("form-data");
3
4const form = new FormData();
5form.append("file", fs.createReadStream("protected.pdf"), "protected.pdf");
6form.append("password", "your-file-password");
7
8const response = await fetch("https://api.extend.ai/files/upload", {
9  method: "POST",
10  headers: {
11    Authorization: "Bearer <API_TOKEN>",
12    "x-extend-api-version": "2026-02-09",
13    ...form.getHeaders(),
14  },
15  body: form,
16});
17
18const data = await response.json();
19// data.id can now be used in subsequent requests via file: { id: data.id }

Error Handling

If you attempt to process a password-protected file without providing a password, the API returns a PASSWORD_PROTECTED_FILE error:

1{
2  "code": "PASSWORD_PROTECTED_FILE",
3  "message": "The file is password protected and cannot be parsed.",
4  "requestId": "req_abc123",
5  "retryable": false
6}