diff --git a/.changes/unreleased/Added-20230517-111720.yaml b/.changes/unreleased/Added-20230517-111720.yaml
new file mode 100644
index 00000000..8e3522ed
--- /dev/null
+++ b/.changes/unreleased/Added-20230517-111720.yaml
@@ -0,0 +1,5 @@
+kind: Added
+body: add openapi docs
+time: 2023-05-17T11:17:20.102509+01:00
+custom:
+  GithubIssue: ""
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 940724ea..c8a3defc 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -11,5 +11,6 @@
   },
   "[python]": {
     "editor.defaultFormatter": "ms-python.black-formatter"
-  }
+  },
+  "conventionalCommits.scopes": ["changelog"]
 }
diff --git a/openapi/json2pdf-openapi.json b/openapi/json2pdf-openapi.json
new file mode 100644
index 00000000..15e9f91d
--- /dev/null
+++ b/openapi/json2pdf-openapi.json
@@ -0,0 +1,190 @@
+{
+  "openapi": "3.0.2",
+  "info": {
+    "title": "json2pdf API for BotC Custom Scripts",
+    "version": "1.0"
+  },
+  "servers": [
+    { "url": "https://p1ntlz7vxk.execute-api.eu-west-2.amazonaws.com/dev" },
+    { "url": "https://p1ntlz7vxk.execute-api.eu-west-2.amazonaws.com/prod" }
+  ],
+  "paths": {
+    "/render": {
+      "options": {
+        "description": "CORS preflight support",
+
+        "tags": ["render"]
+      },
+      "post": {
+        "description": "Render a PDF from a JSON payload",
+        "tags": ["render"],
+        "requestBody": {
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/RenderRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDF rendered successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RenderResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Invalid API key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse403"
+                }
+              }
+            }
+          },
+          "500": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse403"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-api-key"
+      }
+    },
+    "schemas": {
+      "RenderRequest": {
+        "type": "object",
+        "required": ["file"],
+        "properties": {
+          "file": {
+            "type": "file",
+            "description": "BotC custom script JSON file"
+          },
+          "paperSize": {
+            "description": "The preferred paper size: <code>A4</code> or <code>Letter</code>.<br/><small><em>Letter has not been fully tested and refined so may yield unexpected results.</em></small>",
+            "type": "string",
+            "enum": ["A4", "letter"],
+            "default": "A4"
+          },
+          "stNightInfo": {
+            "type": "string",
+            "description": "<code>onesheet</code> generates a single page for the Night Information. There are no descriptions of the actions to perform, simply a list of phases (<em>Dusk, Dawn, … characters, …</em>)<br/><br/><code>twosheet</code> generates one page for each of <em>First Night</em> and <em>Second Night</em> and has the actions to perform for each phase. Generally expected to be printed double-sided.",
+            "enum": ["onesheet", "twosheet"],
+            "default": "twosheet"
+          },
+          "scriptFormat": {
+            "type": "string",
+            "description": "<code>regular</code> format is the default format and is a single page for each page of information (Player Reference, Night Order, etc).<br/><br/><code>easyprint</code> format is intended to be a document that can just be printed and has the correct quantity of pages for players as well as the Storyteller.<br>This option also enables other PDF rendering options such as <em>double-sided printing</em>.",
+            "enum": ["regular", "easyprint"],
+            "default": "regular"
+          },
+          "printFormat": {
+            "type": "string",
+            "description": "The preferred print format: <code>singleSided</code> or <code>doubleSided</code>.<br/><br/>Depending on other options selected this will insert blank pages, or 'one sheet' style Night Info, where necessary to ensure the correct pages are printed on the front and back of each sheet. <strong>Note:</strong>This option is only effective when <em>printFormat</em> is set to <em>doubleSided</em>.",
+            "enum": ["singleSided", "doubleSided"],
+            "default": "singleSided"
+          },
+          "playerNightInfo": {
+            "type": "string",
+            "description": "Some Storytellers like to share the Night Info with players, others prefer to keep it vague. Choose your preference here.<br/><br/>If you choose to share the Night Info with players (<code>yes</code>), the generated PDF will have the Night Info pages included. If you choose to keep it vague (<code>no</code>), the Night Info pages will be omitted from the generated PDF and a blank page will be generated in their place.<br/><br/><strong>Note:</strong> This option is only effective when <em>printFormat</em> is set to <em>doubleSided</em>.",
+            "enum": ["no", "yes"],
+            "default": "no"
+          },
+          "playerCount": {
+            "type": "string",
+            "description": "There's no benefit in printing more copies than you need. Choose the number of players you expect to have in your game and the generated PDF will have the correct number of pages for you to print.<br/><br/><code>teensyville</code>: these are games and scripts suited for 5 and 6 players. <small><em>(7 copies)</em></small> <br/><code>ravenswood_regular</code>: there are enough copies to run games at the full non-traveler player count. Alternatively medium sized towns with space for travellers. <small><em>(16 copies)</em></small> <br/><code>ravenswood_traveler Max</code>: enough copies for a full village and the maximum number of travelers. <small><em>(21 copies)</em></small> <br/><br/><strong>… one for the Storyteller</strong>: each quantity is one more than you may initially expect so that the Storyteller has a copy to refer to. <br/><br/><strong>Note:</strong> This option is only available when <em>scriptFormat</em> format is sset to <em>easyprint</em>.",
+            "enum": [
+              "teensyville",
+              "ravenswood_regular",
+              "ravenswood_traveler"
+            ],
+            "default": "ravenswood_regular"
+          }
+        }
+      },
+      "RenderResponse": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Signed URL for the PDF in AWS S3 bucket",
+            "example": "https://s3.amazonaws.com/botc-pdf-renderer/2020-03-01/1234567890.pdf"
+          },
+          "name": {
+            "type": "string",
+            "description": "Name of the PDF file",
+            "example": "1234567890.pdf"
+          },
+          "version": {
+            "type": "string",
+            "description": "Version of the API used to generate the PDF",
+            "example": "v0.1.0"
+          }
+        }
+      },
+      "ErrorResponse403": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "A summary of the error",
+            "example": "INVALID_API_KEY: check you correctly configured the API key in the source code"
+          },
+          "version": {
+            "type": "string",
+            "description": "A version reference for the entity that generated the error",
+            "example": "infra-arcane-scripts.net:v0.0.2"
+          },
+          "chisel": {
+            "type": "string",
+            "description": "A message from the chisel",
+            "example": "was here"
+          }
+        }
+      },
+      "ErrorResponse500": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Something went wrong"
+          },
+          "version": {
+            "type": "string",
+            "description": "A version reference for the entity that generated the error",
+            "example": "infra-arcane-scripts.net:v0.0.2"
+          },
+          "chisel": {
+            "type": "string",
+            "description": "A message from the chisel",
+            "example": "was here"
+          }
+        }
+      }
+    }
+  }
+}