--- openapi: 3.0.2 info: version: 1.0.0 title: Carbone Copy API description: >- Carbone Copy API for generating documents from templates, data documents, and assets license: name: Apache 2.0 url: "https://www.apache.org/licenses/LICENSE-2.0.html" contact: name: NR Common Service Showcase email: NR.CommonServiceShowcase@gov.bc.ca servers: - url: / description: This Server paths: /health: get: summary: Returns a health check. description: >- This endpoint is used to see if the API is up and running. operationId: getHealth tags: - Health responses: "200": description: Indicates API is running default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /fileTypes: get: summary: Returns a dictionary of supported input template file types and output file types. description: >- This endpoint checks the supported file types defined by the Carbone JS library. operationId: getFileTypes tags: - FileTypes responses: "200": description: Returns the supported combinations of input templates and output file types content: application/json: schema: $ref: "#/components/schemas/FileTypes" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /render/{uid}: get: summary: Check if generated file/report has been cached. description: >- This endpoint returns OK if a generated file can be retrieved from the cache. operationId: getReport parameters: - in: path name: uid schema: type: string required: true description: Hash for file, returned via X-Report-Hash headers when report generated - in: query name: download schema: type: boolean required: false description: Indicate if the response should return the binary file tags: - Render responses: "200": description: Returns OK if file can be found in cache; also returns file if download=true content: application/octet-stream: schema: type: string format: binary description: Raw binary-encoded response "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" delete: summary: Remove file from cache. description: >- This endpoint returns OK if a file has been removed from cache. operationId: deleteReport parameters: - in: path name: uid schema: type: string required: true description: Hash for file, returned via X-Report-Hash headers when report generated tags: - Render responses: "200": description: Returns OK if file was found and removed/deleted "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /template: post: summary: Upload a template description: >- This endpoint accepts a template to be used for report generation/render. operationId: uploadTemplate tags: - Template requestBody: description: Fields required to generate a document required: true content: multipart/form-data: schema: type: object properties: template: type: binary responses: "200": description: Returns the supplied document with variables merged in content: application/json: schema: type: string description: Hash/Key/Id for template headers: X-Template-Hash: schema: type: string description: UUID for template cached on server. example: 742d642a4704eb1babd8122ce0f03f209354279ae8292bb3961d13e21578b855 "400": $ref: "#/components/responses/BadRequest" "405": $ref: "#/components/responses/MethodNotAllowed" "422": $ref: "#/components/responses/UnprocessableEntity" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /template/{uid}: get: summary: Check if template has been cached. description: >- This endpoint returns OK if a template file can be retrieved from the cache. operationId: getTemplate parameters: - in: path name: uid schema: type: string required: true description: Hash for template, returned via X-Template-Hash headers when template uploaded - in: query name: download schema: type: boolean required: false description: Indicate if the response should return the binary file tags: - Template responses: "200": description: Returns OK if file can be found in cache; also returns file if download=true content: application/octet-stream: schema: type: string format: binary description: Raw binary-encoded response "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" delete: summary: Remove file from cache. description: >- This endpoint returns OK if a file has been removed from cache. operationId: deleteTemplate parameters: - in: path name: uid schema: type: string required: true description: Hash for file, returned via X-Template-Hash headers when template uploaded tags: - Template responses: "200": description: Returns OK if file was found and removed/deleted "400": $ref: "#/components/responses/BadRequest" "404": $ref: "#/components/responses/NotFound" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /template/{uid}/render: post: summary: Generate a document from existing Template description: >- This endpoint accepts a document template id and a set (or multiple sets) of substitution variables and merges them into the document. operationId: renderReportFromTemplate tags: - Template parameters: - in: path name: uid schema: type: string required: true description: Hash for template, returned via X-Template-Hash headers when template uploaded requestBody: description: Fields required to generate a document required: true content: application/json: schema: $ref: "#/components/schemas/TemplateObject" responses: "200": description: Returns the supplied document with variables merged in content: application/octet-stream: schema: type: string format: binary description: Raw binary-encoded response headers: Content-Disposition: schema: type: string description: >- Indicates if a browser should render this resource inline or treat as an attachment for download example: attachment; filename=file.pdf Content-Length: schema: type: integer description: >- Length of content. This header is not always returned as it depends on the Content-Type (i.e. text/plain, text/html will not return anything) example: 1234 Content-Type: schema: type: string description: The MIME-type of the binary file payload example: application/pdf X-Report-Name: schema: type: string description: name of the generated file. example: file.pdf X-Template-Hash: schema: type: string description: UUID for template cached on server. example: 742d642a4704eb1babd8122ce0f03f209354279ae8292bb3961d13e21578b855 X-Report-Hash: schema: type: string description: UUID for generated file cached on server. (only applies if options.cacheReport = true) example: 742d642a4704eb1babd8122ce0f03f209354279ae8292bb3961d13e21578b855 "400": $ref: "#/components/responses/BadRequest" "405": $ref: "#/components/responses/MethodNotAllowed" "422": $ref: "#/components/responses/UnprocessableEntity" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /template/render: post: summary: Generate document from inline Template description: >- This endpoint accepts a document template and a set (or multiple sets) of substitution variables and merges them into the document. operationId: uploadTemplateAndRenderReport tags: - Template requestBody: description: Fields required to generate a document required: true content: application/json: schema: $ref: "#/components/schemas/TemplateRenderObject" responses: "200": description: Returns the supplied document with variables merged in content: application/octet-stream: schema: type: string format: binary description: Raw binary-encoded response headers: Content-Disposition: schema: type: string description: >- Indicates if a browser should render this resource inline or treat as an attachment for download example: attachment; filename=file.pdf Content-Length: schema: type: integer description: >- Length of content. This header is not always returned as it depends on the Content-Type (i.e. text/plain, text/html will not return anything) example: 1234 Content-Type: schema: type: string description: The MIME-type of the binary file payload example: application/pdf X-Report-Name: schema: type: string description: name of the generated file. example: file.pdf X-Template-Hash: schema: type: string description: UUID for template cached on server. example: 742d642a4704eb1babd8122ce0f03f209354279ae8292bb3961d13e21578b855 X-Report-Hash: schema: type: string description: UUID for generated file cached on server. (only applies if options.cacheReport = true) example: 742d642a4704eb1babd8122ce0f03f209354279ae8292bb3961d13e21578b855 "400": $ref: "#/components/responses/BadRequest" "405": $ref: "#/components/responses/MethodNotAllowed" "422": $ref: "#/components/responses/UnprocessableEntity" default: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" components: schemas: BadRequest: allOf: - $ref: "#/components/schemas/Problem" - type: object properties: status: example: 400 title: example: Bad Request type: example: "https://httpstatuses.com/400" Error: allOf: - $ref: "#/components/schemas/Problem" - type: object properties: status: example: 500 title: example: Internal Server Error type: example: "https://httpstatuses.com/500" FileTypes: type: object additionalProperties: type: object properties: inputFileType: type: string outputFileTypes: type: array items: type: string example: dictionary: docx: [docx, pdf] xlsx: [docx, pdf, xslx] InlineTemplateObject: required: - content - fileType - encodingType type: object properties: content: type: string description: "String, Buffer or a Stream contents for the attachment" example: PGI+SGVsbG8gV29ybGRcITwvYj4= encodingType: type: string description: >- If set and content is string, then encodes the content to a Buffer using the specified encoding. Example values: 'base64', 'hex', 'binary' etc. Useful if you want to use binary attachments in a JSON formatted email object. enum: - base64 - binary - hex example: base64 fileType: type: string description: The file extension of the encoded content file. example: docx MethodNotAllowed: allOf: - $ref: "#/components/schemas/Problem" - type: object properties: status: example: 405 title: example: Method Not Allowed type: example: "https://httpstatuses.com/500" NotFound: allOf: - $ref: "#/components/schemas/Problem" - type: object properties: status: example: 404 title: example: Not Found type: example: "https://httpstatuses.com/404" Problem: required: - type - title - status - detail properties: type: type: string description: "What type of problem, link to explanation of problem" title: type: string description: "Title of problem, generally the Http Status Code description" status: type: string description: The Http Status code detail: type: string description: Short description of why this problem was raised. TemplateObject: type: object properties: data: type: object description: >- A freeform JSON object of key-value pairs or array of freeform JSON object key-value pairs. All keys must be alphanumeric or underscore. additionalProperties: type: string example: firstName: Jane lastName: Smith title: CEO formatters: type: string description: >- A string that can be transformed into an object. See https://www.npmjs.com/package/telejson for transformations, and https://carbone.io/documentation.html#formatters for more on formatters. example: >- {"myFormatter":"_function_myFormatter|function(data) { return data.slice(1); }","myOtherFormatter":"_function_myOtherFormatter|function(data) {return data.slice(2);}"} options: type: object description: Object containing processing options properties: cacheReport: type: boolean description: >- If true, cache the generated report on server, return the hash/UUID for the file. example: true convertTo: type: string description: >- The desired file extension of the generated document, used for converting to other types of document. If not supplied, will just use the original contentFileType. example: pdf overwrite: type: boolean description: >- For inline template uploading, will allow the template to overwrite if already cached. example: true reportName: type: string description: >- The desired file name of the generated document, can accept template substitution fields from the contexts. If not supplied, will use a random UUID. Extension will be from convertTo. example: "abc_123_{d.firstName}_{d.lastName}" TemplateRenderObject: allOf: - $ref: "#/components/schemas/TemplateObject" - type: object properties: template: allOf: - $ref: "#/components/schemas/InlineTemplateObject" - type: object description: An object containing the document template to merge into ValidationError: allOf: - $ref: "#/components/schemas/Problem" - type: object required: - errors properties: errors: type: array items: type: object required: - message properties: value: type: object description: Contents of the field that was in error. example: utf-8x message: type: string description: The error message for the field. example: Invalid value `encoding`. status: example: 422 title: example: Unprocessable Entity type: example: "https://httpstatuses.com/422" responses: BadRequest: description: Request is missing content or is malformed content: application/json: schema: $ref: "#/components/schemas/BadRequest" Error: description: Unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" Forbidden: description: Lack required role to perform action MethodNotAllowed: description: Method not allowed content: application/json: schema: $ref: "#/components/schemas/MethodNotAllowed" NoContent: description: Accepted and no content NotFound: description: Not found content: application/json: schema: $ref: "#/components/schemas/NotFound" UnauthorizedError: description: Access token is missing or invalid UnprocessableEntity: description: >- The server was unable to process the contained instructions. Generally validation error(s). content: application/json: schema: $ref: "#/components/schemas/ValidationError"