openapi: 3.0.0
info:
title: FileForge API
description: FileForge API for document operations.
version: 0.1.0
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
apiKey:
type: apiKey
name: X-API-Key
in: header
schemas:
def-0:
type: object
required:
- statusCode
- code
- message
description: Generic error response schema
properties:
statusCode:
type: number
description: The HTTP status code
example: 400
code:
type: string
description: A machine-readable error code
example: BAD_REQUEST
message:
type: string
description: >-
A human-readable message. This field may also provide additional
context to the error code.
example: Bad request
title: ErrorSchema
paths:
/status/:
get:
operationId: getStatus
description: Get the status of the API
x-fern-availability: generally-available
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
status:
type: string
/pdf/docx/:
post:
operationId: convertDOCXtoPDF
summary: Converts a DOC or DOCX document to PDF.
tags:
- PDF
description: >-
Converts a Microsoft Word document (.DOCX or .DOC) file to a PDF
document.
This service uses a LibreOffice headless server to perform the
conversion, and may not support all features of the original document.
**Known discrepancies**
* Some fonts may not be available in the server, and may be substituted
by a closest match.
* Some complex formatting may not be preserved, such as background
graphics.
**Variables**
Variable replacement is supported with various methods:
* Templated litterals: `{{name}}`
* Word variables, as listed in the document metadata: `{DOCVARIABLE
"name"}`
To enable variable replacement as Word variables for your account,
please contact the FileForge support.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
options:
description: >-
Conversion options. This field is required even if empty.
**Options**
* `templateLiterals`: Map of template literals to replace in
the document. Template literals should be enclosed in double
curly braces, e.g. `{{name}}`. Variables name can contain
alphanumeric characters and hyphens. All variables are
case-sensitive. The value for each variable should be a
string. If a value of undefined is passed, the variable will
not be removed from the document. If you need to remove a
variable, pass an empty string as the value.
**NB** variables should **not** have surrounding spaces,
e.g. `{{ name }}`.
**Example**
In the Word document: `{{name}} {{nickname}}. was born on
{{date}}.`
```json
{
"templateLiterals": {
"name": "John Doe",
"date": "2021-12-31",
"nickname": ""
}
}
```
There will not be an error if a variable is not found in the
document, nor if variables found in the document are not in
the options.
type: object
properties:
keepOriginalStyles:
type: boolean
description: >-
Whether to keep the text formatting of the variables in
the document. Default is true.
templateLiterals:
type: object
description: Map of template literals to replace in the document.
additionalProperties:
type: string
file:
description: >-
The Microsoft Word document (.DOCX or .DOC) file to convert
to PDF.
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
x-fern-sdk-method-name: fromDocx
x-fern-availability: beta
responses:
'201':
description: PDF Document generated successfully
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/docx/'
-H 'accept: application/pdf'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={"keepOriginalStyles":true,"templateLiterals":{"additionalProp1":"string","additionalProp2":"string","additionalProp3":"string"}};type=application/json'
-F 'file=@demo.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const docxFile = fs.createReadStream(
__dirname + "/samples/document-simple.docx",
);
const pdfStream = await ff.pdf.fromDocx(
docxFile,
{},
{
timeoutInSeconds: 30,
},
);
pdfStream.pipe(fs.createWriteStream("./result_docx.pdf"));
console.log("PDF conversion successful. Stream ready.");
} catch (error) {
console.error("Error during PDF conversion:", error);
throw error;
}
})();
/pdf/generate/:
post:
operationId: generatePDFDocument
summary: Generates a PDF document from HTML and web technologies.
tags:
- PDF
description: Generates a PDF document from web assets.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- files
properties:
options:
description: Conversion options. This field is required even if empty.
type: object
properties:
test:
type: boolean
description: >-
Generate a test document instead of a production
document. The generated document will contain a
watermark. Defaults to true.
default: true
host:
type: boolean
description: >-
If enabled, the document will be hosted by FileForge and
a presigned URL will be returned.
default: false
expiresAt:
type: string
format: date-time
description: >-
If host is enabled, the expiration date of the presigned
URL. Defaults to 7 days from now. Cannot exceed 7 days
from now.
fileName:
type: string
description: >-
The name of the generated PDF file. Defaults to
document. The file name should not contain extensions
nor path traversals.
default: document
files:
description: >-
Files to generate the PDF document from.
An `index.html` file is required, and will be used as the
main document. Other documents may also be attached, such as
stylesheets or images. The path in the `filename` part of
the multipart attachement will be respected during
generation.
**Important notice**: during generation, the `index.html`
file will be processed to include the base URL of the
document. This is required for assets to be loaded
correctly. To link your assets from the HTML file, you
should not use a leading slash in the URL. For example, use
`
` instead of `
`.
allOf:
- {}
- type: array
items:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
x-fern-sdk-method-name: generate
x-fern-availability: generally-available
responses:
'201':
description: PDF Document generated successfully
content:
application/pdf:
schema:
type: string
format: binary
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: URL to the generated PDF document
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
'502':
description: Bad Gateway
content:
application/json:
schema:
description: Bad Gateway
$ref: '#/components/schemas/def-0'
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/generate/'
-H 'accept: application/pdf'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={"test":true,"host":false,"expiresAt":"2024-06-21T12:10:51.382Z","fileName":"document"};type=application/json'
-F 'files=@index.html;type=text/html'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const pdf = await ff.pdf.generate(
[
new File(
["Hello world
"],
"index.html",
{
type: "text/html",
},
),
],
{
options: {
host: true,
},
},
{
timeoutInSeconds: 30,
},
);
console.log(pdf.url);
} catch (error) {
console.error("Error during PDF generation:", error);
throw error;
}
})();
/pdf/merge/:
post:
operationId: mergePDFDocuments
summary: Merges multiple PDF documents into a single PDF document.
tags:
- PDF
description: Merges multiple PDF documents into a single PDF document.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- files
properties:
options:
type: object
properties: {}
files:
allOf:
- {}
- type: array
items:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
x-fern-sdk-method-name: merge
x-fern-availability: generally-available
responses:
'201':
description: PDF Document generated successfully
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/merge/'
-H 'accept: application/pdf'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={};type=application/json'
-F 'files=@doc.pdf;type=application/pdf'
-F 'files=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const pdfFiles = [
fs.createReadStream(__dirname + "/pdf1.pdf"),
fs.createReadStream(__dirname + "/pdf2.pdf"),
];
const mergedPdfStream = await ff.pdf.merge(
pdfFiles,
{
options: {
// Specify merge options if any
},
},
{
timeoutInSeconds: 60,
},
);
mergedPdfStream.pipe(fs.createWriteStream("./result_merge.pdf"));
console.log("PDF merge successful. Stream ready.");
} catch (error) {
console.error("Error during PDF merge:", error);
throw error;
}
})();
/pdf/form/detect/:
post:
operationId: detectPDFFormFields
summary: Detect form fields in a PDF document
tags:
- PDF
- form
description: >-
Returns a list of form fields detected in the PDF document, along with
their location, options and requirements. For a more visual
representation, use the /pdf/form/mark endpoint.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
options:
type: object
properties: {}
file:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
- form
x-fern-sdk-method-name: detect
x-fern-availability: beta
responses:
'200':
description: Document fields detected successfully
content:
application/json:
schema:
description: Document fields detected successfully
type: array
items:
type: object
properties:
name:
type: string
required:
type: boolean
readOnly:
type: boolean
locations:
type: array
items:
type: object
properties:
x:
type: number
'y':
type: number
width:
type: number
height:
type: number
required:
- x
- 'y'
- width
- height
required:
- name
- type
- required
- readOnly
- locations
anyOf:
- type: object
properties:
type:
type: string
enum:
- PDFCheckBox
isChecked:
type: boolean
required:
- type
- type: object
properties:
type:
type: string
enum:
- PDFDropdown
- PDFOptionList
options:
type: array
items:
type: string
isMultiselect:
type: boolean
selected:
type: array
items:
type: string
isEditable:
type: boolean
required:
- type
- type: object
properties:
type:
type: string
enum:
- PDFRadioGroup
options:
type: array
items:
type: string
selected:
type: string
isMutuallyExclusive:
type: boolean
isOffToggleable:
type: boolean
required:
- type
- type: object
properties:
type:
type: string
enum:
- PDFTextField
defaultValue:
type: string
isPassword:
type: boolean
isRichFormatted:
type: boolean
isScrollable:
type: boolean
isCombed:
type: boolean
isMultiline:
type: boolean
isFileSelector:
type: boolean
maxLength:
type: number
required:
- type
- type: object
properties:
type:
type: string
enum:
- PDFSignature
defaultValue:
type: string
required:
- type
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |
curl -X 'POST'
'https://api.fileforge.com/pdf/form/detect/'
-H 'accept: application/json'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={};type=application/json'
-F 'file=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const resultObject = await ff.pdf.form.detect(
new File(
[fs.readFileSync(__dirname + "/samples/form.pdf")],
"form.pdf",
{
type: "application/pdf",
},
),
{ options: {} },
);
console.log(resultObject);
} catch (error) {
console.error("Error during PDF form detect:", error);
throw error;
}
})();
/pdf/form/mark/:
post:
operationId: markPDFFormFields
summary: Mark form fields in a PDF document
tags:
- PDF
- form
description: >-
Returns a modified PDF document with form fields marked with a green
border, and hover text showing the field name.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
options:
type: object
properties: {}
file:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
- form
x-fern-sdk-method-name: mark
x-fern-availability: beta
responses:
'201':
description: Marked PDF Document generated successfully
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/form/mark/'
-H 'accept: application/pdf'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={};type=application/json'
-F 'file=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const pdfStream = await ff.pdf.form.mark(
new File(
[fs.readFileSync(__dirname + "/samples/form.pdf")],
"form.pdf",
{
type: "application/pdf",
},
),
{ options: {} },
);
pdfStream.pipe(fs.createWriteStream("./result_mark.pdf"));
} catch (error) {
console.error("Error during PDF form mark:", error);
throw error;
}
})();
/pdf/form/fill/:
post:
operationId: fillPDFFormFields
summary: Fill form fields in a PDF document
tags:
- PDF
- form
description: >-
Returns a modified PDF document with filled form fields. A subset of
fields can be filled.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
options:
type: object
required:
- fields
properties:
fields:
type: array
description: Fields to fill or change in the PDF document.
items:
type: object
anyOf:
- type: object
required:
- name
- type
- value
properties:
name:
description: >-
Name of the field to fill. This must match an
exact name from the PDF document. To detect
all fields, use the /pdf/form/fields endpoint,
or use the /pdf/form/mark endpoint to get an
annotated PDF with each detected field.
type: string
type:
type: string
enum:
- PDFTextField
value:
type: string
- type: object
required:
- name
- type
- checked
properties:
name:
description: >-
Name of the field to fill. This must match an
exact name from the PDF document. To detect
all fields, use the /pdf/form/fields endpoint,
or use the /pdf/form/mark endpoint to get an
annotated PDF with each detected field.
type: string
type:
type: string
enum:
- PDFCheckBox
checked:
type: boolean
- type: object
required:
- name
- type
- selected
properties:
name:
description: >-
Name of the field to fill. This must match an
exact name from the PDF document. To detect
all fields, use the /pdf/form/fields endpoint,
or use the /pdf/form/mark endpoint to get an
annotated PDF with each detected field.
type: string
type:
type: string
enum:
- PDFOptionList
- PDFDropdown
selected:
type: array
items:
type: string
- type: object
required:
- name
- type
- selected
properties:
name:
description: >-
Name of the field to fill. This must match an
exact name from the PDF document. To detect
all fields, use the /pdf/form/fields endpoint,
or use the /pdf/form/mark endpoint to get an
annotated PDF with each detected field.
type: string
type:
type: string
enum:
- PDFRadioGroup
selected:
type: string
file:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
- form
x-fern-sdk-method-name: fill
x-fern-availability: beta
responses:
'201':
description: PDF Document filled successfully
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/form/fill/'
-H 'accept: application/pdf'
-H 'X-API-Key: '
-H 'Content-Type: multipart/form-data'
-F 'options={"fields":[{"name":"string","type":"PDFTextField","value":"string"},{"name":"string","type":"PDFCheckBox","checked":true},{"name":"string","type":"PDFOptionList","selected":["string"]},{"name":"string","type":"PDFRadioGroup","selected":"string"}]};type=application/json'
-F 'file=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const formFillRequest = {
options: {
fields: [
{
name: "Producer Name",
type: "PDFTextField",
value: "Titouan Launay",
} as FormFillRequestOptionsFieldsItemValue,
],
},
};
const requestOptions = {
timeoutInSeconds: 60,
maxRetries: 3,
};
const filledPdfStream = await ff.pdf.form.fill(
new File(
[fs.readFileSync(__dirname + "/samples/form.pdf")],
"form.pdf",
{
type: "application/pdf",
},
),
formFillRequest,
requestOptions,
);
filledPdfStream.pipe(fs.createWriteStream("./result_filled.pdf"));
console.log("PDF form filling successful. Stream ready.");
} catch (error) {
console.error("Error during PDF form filling:", error);
}
})();
/pdf/split/:
post:
operationId: splitPDFDocuments
summary: Splits a PDF document into 2 PDF documents.
tags:
- PDF
description: >-
Splits a PDF document into 2 PDF documents. Returns a zip file
containing the 2 documents. Each document is named after the original
document with a suffix added to indicate the range of pages it contains.
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- options
- file
properties:
options:
required:
- splitPage
type: object
properties:
splitPage:
type: integer
minimum: 1
description: >-
The page number to split the document at (the page will
be included in the first document)
file:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
x-fern-sdk-method-name: split
x-fern-availability: generally-available
responses:
'201':
description: ZIP file generated successfully
content:
application/zip:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/split/'
-H 'accept: application/zip'
-H 'X-API-Key : '
-H 'Content-Type: multipart/form-data'
-F 'options={splitPage:1};type=application/json'
-F 'file=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const extractRequest = {
options: {
start: 1,
end: 1,
},
};
const requestOptions = {
timeoutInSeconds: 60,
maxRetries: 3,
};
const extractStream = await ff.pdf.extract(
new File(
[fs.readFileSync(__dirname + "/samples/form.pdf")],
"form.pdf",
{
type: "application/pdf",
},
),
extractRequest,
requestOptions,
);
await pipeline(
extractStream,
fs.createWriteStream("./result_extract.pdf"),
);
console.log("Split successful. Zip Stream ready.");
} catch (error) {
console.error("Error during PDF splitting:", error);
}
})();
/pdf/extract/:
post:
operationId: extractPDFDocuments
summary: Extract a range of pages from a PDF document.
tags:
- PDF
description: >-
Extracts a range of pages from a PDF document. The start and end pages
are included in the extracted document. The extracted document is named
after the original document with a suffix added to indicate the range of
pages it contains (ex:document_extracted_$start_$end.pdf).
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- options
- file
properties:
options:
required:
- start
- end
type: object
properties:
start:
type: integer
minimum: 1
description: The page number to split the document at
end:
type: integer
minimum: 1
description: The page number to split the document at
file:
type: string
format: binary
encoding:
options:
contentType: application/json
required: true
security:
- apiKey: []
x-fern-sdk-group-name:
- pdf
x-fern-sdk-method-name: extract
x-fern-availability: generally-available
responses:
'201':
description: Extracted PDF file generated successfully
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Bad request
content:
application/json:
schema:
description: Bad request
$ref: '#/components/schemas/def-0'
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
$ref: '#/components/schemas/def-0'
'500':
description: Internal server error
x-fern-examples:
- response:
body: null
code-samples:
- sdk: curl
code: |-
curl -X 'POST'
'https://api.fileforge.com/pdf/extract/'
-H 'accept: application/json'
-H 'X-API-Key
: '
-H 'Content-Type: multipart/form-data'
-F 'options={start:1,end:1};type=application/json'
-F 'file=@document (18).pdf;type=application/pdf'
- sdk: typescript
code: |-
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
(async () => {
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
try {
const extractRequest = {
options: {
start: 1,
end: 1,
},
};
const requestOptions = {
timeoutInSeconds: 60,
maxRetries: 3,
};
const extractStream = await ff.pdf.extract(
new File(
[fs.readFileSync(__dirname + "/samples/form.pdf")],
"form.pdf",
{
type: "application/pdf",
},
),
extractRequest,
requestOptions,
);
await pipeline(
extractStream,
fs.createWriteStream("./result_extract.pdf"),
);
console.log("Split successful. Zip Stream ready.");
} catch (error) {
console.error("Error during PDF splitting:", error);
}
})();
servers:
- url: https://api.fileforge.com
description: Tunnel server
- url: http://localhost:3000
description: Development server
tags:
- name: PDF
description: PDF operations
- name: form
description: PDF form operations