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:
/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
/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. If more than 7 days, the
document will be hosted for a monthly fee.
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
allowViewing:
type: boolean
description:
If enabled, the document will be viewable in the web app. Defaults
to false. This may go against the privacy policy of your
application.
default: false
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"
/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:
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. If more than 7 days, the
document will be hosted for a monthly fee.
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
allowViewing:
type: boolean
description:
If enabled, the document will be viewable in the web app. Defaults
to false. This may go against the privacy policy of your
application.
default: false
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
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: URL to the merged 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
/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:
aiDetection:
type: object
properties:
enable:
type: boolean
default: false
limit:
type: number
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
aiDetectedName:
type: object
required:
- name
- score
properties:
name:
type: string
score:
type: number
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
/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
/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:
flattenForm:
type: boolean
description:
Flatten the form fields after filling them. This will make the PDF
form uneditable.
default: false
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
/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
/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
/pdf/insert/:
post:
operationId: insertPDFDocuments
summary: Insert a PDF document into another PDF document at a specified page.
tags:
- PDF
description:
"Insert a PDF document into another PDF document at a specified
page. The inserted document is named after the original document with a
suffix added to indicate the range of pages it contains
(ex:document\\_inserted\\_\\$insertPage\\_\\$document2.pdf). Note: The
first document is the parent document and the second document is the
document to be inserted."
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- options
- files
properties:
options:
required:
- insertPage
type: object
properties:
insertPage:
type: integer
minimum: 1
description: The page number to insert the document at
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: insert
x-fern-availability: generally-available
responses:
"201":
description: PDF file inserted 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
/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
servers:
- url: https://api.fileforge.com
description: Global Server
tags:
- name: PDF
description: PDF operations
- name: form
description: PDF form operations