> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a Template

> Use this endpoint to upload a new template to the system. It accepts a `.tpl` file that defines the structure and logic of the report.  
  
The file must be formatted according to the desired output type — HTML, XML, CSV, PDF, or TXT — using [Reporter](/en/reporter) plugin blocks where applicable.  
  
Regardless of the format, the file must **always** be saved with a `.tpl` extension for the template to function correctly.

<Tip>
  Need a sample to test this endpoint? <b><a href="https://drive.google.com/file/d/1i8QP2Uk4ZGMy7Zk28b_c9e2Zwb9i65-X/view?usp=sharing" target="_blank" rel="noopener noreferrer">Click here to download a sample .tpl file.</a></b>
</Tip>


## OpenAPI

````yaml /en/openapi/v3-current/reporter.yaml post /v1/templates
openapi: 3.1.0
info:
  title: Reporter
  description: ''
  version: 1.2.0
servers:
  - url: https://reporter.sandbox.lerian.net
security: []
tags: []
paths:
  /v1/templates:
    post:
      tags:
        - Templates API
      summary: Upload a Template
      description: >-
        Use this endpoint to upload a new template to the system. It accepts a
        `.tpl` file that defines the structure and logic of the report.  
          
        The file must be formatted according to the desired output type — HTML,
        XML, CSV, PDF, or TXT — using [Reporter](/en/reporter) plugin blocks
        where applicable.  
          
        Regardless of the format, the file must **always** be saved with a
        `.tpl` extension for the template to function correctly.
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/XOrganizationId'
        - $ref: '#/components/parameters/XIdempotency'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                template:
                  format: binary
                  type: string
                  description: >-
                    The .tpl file you've created to serve as the template
                    definition.
                  example: '@example-file'
                outputFormat:
                  type: string
                  enum:
                    - HTML
                    - CSV
                    - XML
                    - PDF
                    - TXT
                  description: The format of the report that the template will generate.
                  example: TXT
                description:
                  description: A brief description about the template.
                  type: string
                  example: List of holders
              required:
                - template
                - outputFormat
                - description
            example:
              template: '@example-file'
              outputFormat: TXT
              description: List of holders
      responses:
        '200':
          description: >-
            Indicates that the resource was successfully created and the
            operation was completed as expected.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the transaction was just processed. If the
            value is true, the response is a replay of a previously processed
            request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
              example:
                id: 0196b270-a315-7137-9408-3f16af2685e1
                outputFormat: TXT
                description: List of holders
                fileName: 0196b270-a315-7137-9408-3f16af2685e1.tpl
                createdAt: '2025-05-09T00:27:28.405080783Z'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Error0001:
                  $ref: '#/components/examples/Error0001'
                Error0002:
                  $ref: '#/components/examples/Error0002'
                Error0003:
                  $ref: '#/components/examples/Error0003'
                Error0004:
                  $ref: '#/components/examples/Error0004'
                Error0005:
                  $ref: '#/components/examples/Error0005'
                Error0006:
                  $ref: '#/components/examples/Error0006'
                Error0007:
                  $ref: '#/components/examples/Error0007'
                Error0008:
                  $ref: '#/components/examples/Error0008'
                Error0015:
                  $ref: '#/components/examples/Error0015'
                Error0016:
                  $ref: '#/components/examples/Error0016'
                Error0017:
                  $ref: '#/components/examples/Error0017'
                Error0018:
                  $ref: '#/components/examples/Error0018'
                Error0019:
                  $ref: '#/components/examples/Error0019'
                Error0032:
                  $ref: '#/components/examples/Error0032'
      security: []
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: >-
        The authorization token in the 'Bearer <token>' format.  


        **Important:** This header is required if your environment has Access
        Manager enabled. For more information, refer to the [Access
        Manager](/en/access-manager) documentation.
      required: false
      schema:
        type: string
    ContentType:
      name: Content-Type
      in: header
      description: >-
        The request content type. **Important:** For this endpoint, it must be
        `multipart/form-data`.
      required: true
      example: multipart/form-data
      schema:
        type: string
    XOrganizationId:
      name: X-Organization-id
      in: header
      description: The unique identifier of the Organization associated with the request.
      required: true
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
    XIdempotency:
      name: X-Idempotency
      in: header
      description: >-
        Optional idempotency key for safe retries. If omitted, the server may
        generate one automatically.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      required: false
      schema:
        type: string
  schemas:
    TemplateResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique ID that identifies the template (UUID format).
        outputFormat:
          type: string
          description: The format of the generated output (e.g., HTML, CSV, PDF, TXT, XML).
        description:
          type: string
          description: Briefly describes what the template is for or what it contains.
        fileName:
          type: string
          description: >-
            The name of the template file as stored in the system. Follows the
            `<template_id>.tpl` format.
        createdAt:
          type: string
          description: Timestamp indicating when the template was created.
        updatedAt:
          type: string
          description: Timestamp indicating the last time the template was updated.
      description: Details about the template that was created.
    Error:
      type: object
      properties:
        code:
          type: string
          description: A unique, stable identifier for the error.
        title:
          type: string
          description: A brief summary of the issue.
        message:
          type: string
          description: Detailed guidance for resolving the error.
      description: Response message error.
      required:
        - code
        - title
        - message
  headers:
    XIdempotencyReplayed:
      description: >-
        Indicates whether the response was replayed from cache (`true`) or is a
        fresh response (`false`). Always check this header to avoid processing
        the same operation twice on your side.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      schema:
        type: boolean
      example: false
  examples:
    Error0001:
      summary: Missing required fields
      value:
        code: TPL-0001
        title: Missing required fields
        message: >-
          One or more required fields are missing. Please ensure all required
          fields like description, template, and outputFormat are included.
    Error0002:
      summary: Invalid file format
      value:
        code: TPL-0002
        title: Invalid file format
        message: >-
          The uploaded file must be a .tpl file. Other formats are not
          supported.
    Error0003:
      summary: Invalid output format
      value:
        code: TPL-0003
        title: Invalid output format
        message: 'The outputFormat field must be one of: html, csv, PDF or xml.'
    Error0004:
      summary: Invalid header
      value:
        code: TPL-0004
        title: Invalid header
        message: >-
          One or more header values are missing or incorrectly formatted. Please
          verify required headers %VALUE.
    Error0005:
      summary: Invalid File Uploaded
      value:
        code: TPL-0005
        title: Invalid File Uploaded
        message: >-
          The file you submitted is invalid. Please check the uploaded file with
          error: %VALUE.
    Error0006:
      summary: Error Empty File
      value:
        code: TPL-0006
        title: Error Empty File
        message: The file you submitted is empty. Please check the uploaded file.
    Error0007:
      summary: Error File Content Invalid
      value:
        code: TPL-0007
        title: Error File Content Invalid
        message: >-
          The file content is invalid because is not %s. Please check the
          uploaded file.
    Error0008:
      summary: Invalid Map Fields
      value:
        code: TPL-0008
        title: Invalid Map Fields
        message: The field on template file is invalid. Invalid field %s on %s.
    Error0015:
      summary: Unexpected Fields in the Request
      value:
        code: TPL-0015
        title: Unexpected Fields in the Request
        message: >-
          The request body contains more fields than expected. Please send only
          the allowed fields as per the documentation. The unexpected fields are
          listed in the fields object.
    Error0016:
      summary: Missing Fields in Request
      value:
        code: TPL-0016
        title: Missing Fields in Request
        message: >-
          Your request is missing one or more required fields. Please refer to
          the documentation to ensure all necessary fields are included in your
          request.
    Error0017:
      summary: Bad Request
      value:
        code: TPL-0017
        title: Bad Request
        message: >-
          The server could not understand the request due to malformed syntax.
          Please check the listed fields and try again.
    Error0018:
      summary: Internal Server Error
      value:
        code: TPL-0018
        title: Internal Server Error
        message: >-
          The server encountered an unexpected error. Please try again later or
          contact support.
    Error0019:
      summary: Invalid Query Parameter
      value:
        code: TPL-0019
        title: Invalid Query Parameter
        message: >-
          One or more query parameters are in an incorrect format. Please check
          the following parameters '%v' and ensure they meet the required format
          before trying again.
    Error0032:
      summary: Script Tag Detected
      value:
        code: TPL-0032
        title: Script Tag Detected
        message: >-
          The template file contains a script tag and is not allowed. Please
          check the template file and try again.

````