openapi: 3.0.0
info:
title: Fileforge API
description: Fileforge API for document operations.
version: 0.1.0
components:
securitySchemes:
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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
try {
const docxFile = fs.createReadStream(__dirname + "/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);
}
})();
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
/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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
const HTML = `Hello world
"`;
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
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 conversion:", error);
}
})();
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"
/pdf/merge/:
post:
operationId: mergePDFDocuments
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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
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);
}
})();
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
/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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
try {
const resultObject = await ff.pdf.form.detect(
new File([fs.readFileSync(__dirname + "/form.pdf")], "form.pdf", {
type: "application/pdf",
}),
{ options: {} },
);
console.log(resultObject);
} catch (error) {
console.error("Error during PDF merge:", error);
}
})();
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
"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
/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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
try {
const pdfStream = await ff.pdf.form.mark(
new File([fs.readFileSync(__dirname + "/form.pdf")], "form.pdf", {
type: "application/pdf",
}),
{ options: {} },
);
pdfStream.pipe(fs.createWriteStream("./result_mark.pdf"));
} catch (error) {
console.error("Error during PDF merge:", error);
}
})();
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
/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
x-fern-examples:
- response:
body:
code-samples:
- sdk: typescript
code: |
import { FileforgeClient } from "@fileforge/client";
import * as fs from "fs";
const ff = new FileforgeClient({
apiKey: process.env.FILEFORGE_API_KEY,
});
(async () => {
try {
const formFillRequest = {
options: {
fields: [
{
name: "Producer Name",
type: "PDFTextField",
value: "Titouan Launay",
},
],
},
};
const requestOptions = {
timeoutInSeconds: 60,
maxRetries: 3,
};
const filledPdfStream = await ff.pdf.form.fill(
new File([fs.readFileSync(__dirname + "/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);
}
})();
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
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