openapi: 3.2.0
info:
  contact:
    url: https://support.templafy.com/hc/en-us/requests/new
    name: Submit support ticket
  description: Please refer to our documentation for guidelines and examples.
  title: Templafy Public Data Sources API
  version: v4
  termsOfService: https://www.templafy.com/templafy-saas-agreement/
servers:
- variables:
    tenantId:
      default: ''
      description: Your Templafy subdomain, i.e., https://{TenantId}.api.templafy.com
  url: https://{tenantId}.api.templafy.com/v4
tags:
- name: Data Sources
paths:
  /data-sources:
    get:
      tags:
      - Data Sources
      summary: Lists all existing data sources
      description: Returns a list of all data sources and the schema of their fields.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataSource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - bearerAuth:
        - datasources.read
        - datasources.readwrite
      operationId: getDataSources
      x-operation-id-source: derived
    post:
      tags:
      - Data Sources
      summary: Creates a new data source
      description: Creates a new data source to contain data source items to represent your data.
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateDataSourceRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataSourceRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateDataSourceRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateDataSourceRequest'
      responses:
        '201':
          description: Responds with the new data source's URL in the Location header and its details in the body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundProblemDetails'
      security:
      - bearerAuth:
        - datasources.readwrite
      operationId: postDataSources
      x-operation-id-source: derived
  /data-sources/{id}:
    get:
      tags:
      - Data Sources
      summary: Gets an existing data source
      description: Returns a single data source and the schema of its fields.
      parameters:
      - name: id
        in: path
        description: The identifier of the data source
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundProblemDetails'
      security:
      - bearerAuth:
        - datasources.read
        - datasources.readwrite
      operationId: getDataSourcesById
      x-operation-id-source: derived
    patch:
      tags:
      - Data Sources
      summary: Updates an existing data source
      description: This is a PATCH operation. Any fields not included in the request will remain unchanged on the server.
      parameters:
      - name: id
        in: path
        description: The identifier of the data source
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateDataSourceRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDataSourceRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateDataSourceRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateDataSourceRequest'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundProblemDetails'
      security:
      - bearerAuth:
        - datasources.readwrite
      operationId: patchDataSourcesById
      x-operation-id-source: derived
    delete:
      tags:
      - Data Sources
      summary: Deletes an existing data source
      parameters:
      - name: id
        in: path
        description: The identifier of the data source
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundProblemDetails'
        '423':
          description: Delete will fail for data source with hard dependencies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceObjectLockedProblemDetails'
      security:
      - bearerAuth:
        - datasources.readwrite
      operationId: deleteDataSourcesById
      x-operation-id-source: derived
components:
  schemas:
    DataSource:
      required:
      - fields
      - id
      - name
      type: object
      properties:
        id:
          type: integer
          description: Unique data source identifier.
          format: int64
        name:
          minLength: 1
          type: string
          description: Data source name. It must be unique.
        description:
          type:
          - string
          - 'null'
          description: Data source description.
        fields:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/TextFieldSchema'
            - $ref: '#/components/schemas/NumberFieldSchema'
            - $ref: '#/components/schemas/ReferenceFieldSchema'
            - $ref: '#/components/schemas/ImageFieldSchema'
            - $ref: '#/components/schemas/LanguageFieldSchema'
            - $ref: '#/components/schemas/FontFieldSchema'
            - $ref: '#/components/schemas/ColorThemeFieldSchema'
      additionalProperties: false
      example:
        id: '638247997499047080'
        name: Cities
        description: Cities in which we have offices
        fields:
        - id: 0
          name: Name
          type: text
          isRequired: true
          isLocked: true
          isMultipleLines: false
        - id: 1
          name: History
          type: text
          isRequired: false
          isLocked: false
          isMultipleLines: true
          defaultValue: The city was established in the year 1652 by Dutch explorers...
        - id: 2
          name: Population
          type: number
          isRequired: true
          isLocked: false
          defaultValue: 100222
        - id: 3
          name: Country
          type: reference
          isRequired: true
          isLocked: false
          defaultValue: '638247997437572266'
          referenceDataSourceId: '638247997437572264'
        - id: 4
          name: Flag
          type: image
          isRequired: false
          isLocked: false
        - id: 5
          name: PreferredLanguage
          type: language
          isRequired: false
          isLocked: false
          defaultValue: German
        - id: 6
          name: PreferredFont
          type: font
          isRequired: false
          isLocked: false
        - id: 7
          name: PreferredColourTheme
          type: colorTheme
          isRequired: false
          isLocked: false
    LanguageFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - type: object
        properties:
          defaultValue:
            type:
            - string
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
        additionalProperties: false
      example:
        id: 4
        name: PreferredLanguage
        type: language
        isRequired: false
        isLocked: false
        defaultValue: German
    ValidationProblemDetails:
      type: object
      properties:
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        traceId:
          type:
          - string
          - 'null'
      additionalProperties: false
      example:
        errors:
        - name: The name field is required
        - data: The input was invalid
        title: One or more validation errors occurred.
        status: 400
        traceId: d61f7ce-cccb-4e5b-8727-3b68a61a0559
    LockReason:
      enum:
      - hardDependency
      - restrictedAccess
      type: string
      description: The reason the resource is locked. It is either because the resource is depended upon by another resource or the resource has restricted access and cannot be modified.
    CreateReferenceFieldSchemaRequest:
      allOf:
      - $ref: '#/components/schemas/CreateDataSourceFieldSchemaRequest'
      - required:
        - referenceDataSourceId
        type: object
        properties:
          referenceDataSourceId:
            type: integer
            description: The id of the data source that the field references.
            format: int64
          defaultReferencedItemId:
            type:
            - integer
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
            format: int64
        additionalProperties: false
      example:
        name: Country
        type: reference
        referenceDataSourceId: '637989101951089955'
        defaultReferencedItemId: '638249311425155568'
        isRequired: true
    DataSourceObjectLockedProblemDetails:
      type: object
      properties:
        lockReason:
          $ref: '#/components/schemas/LockReason'
        dependencies:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Dependency'
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        traceId:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: The reason the resource is locked with an optional array of dependencies. Dependencies array is populated only when lockedReason is hardDependency and contains a maximum of 50 items per sourceEntityType
      example:
        title: Locked
        detail: The data source item cannot be deleted because it has been used by another resource.
        status: 423
        traceId: d61f7ce-cccb-4e5b-8727-3b68a61a0559
        lockReason: hardDependency
        dependencies:
        - sourceEntityType: dataSourceItem
          sourceEntityId: '1031936131644784655'
          description: There is a dependency from 'DataSourceItem'.
    ImageFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - type: object
        additionalProperties: false
      example:
        id: 2
        name: Logo
        type: image
        isRequired: false
        isLocked: false
    ReferenceFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - required:
        - referenceDataSourceId
        type: object
        properties:
          referenceDataSourceId:
            type: integer
            description: The id of the data source that the field references.
            format: int64
          defaultValue:
            type:
            - integer
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
            format: int64
        additionalProperties: false
      example:
        id: 3
        name: Region
        type: reference
        isRequired: true
        isLocked: false
        defaultValue: '638247997437572266'
        referenceDataSourceId: '638247997437572264'
    UpdateDataSourceRequest:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: Data source description. If null, description will be removed.
      additionalProperties: false
      example:
        description: This is an updated description
    DataSourceFieldSchema:
      required:
      - id
      - isLocked
      - isRequired
      - name
      - type
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: Data source field schema type.
          readOnly: true
        id:
          type: integer
          description: Unique data source field schema identifier
          format: int32
          readOnly: true
        name:
          minLength: 1
          type: string
          description: Data source field schema name. It must be unique within the data source.
          readOnly: true
        isLocked:
          type: boolean
          description: Value indicating whether data source schema is locked. If true, the field cannot be deleted or modified.
          readOnly: true
        isRequired:
          type: boolean
          description: Whether the field is required. If true, the field must be filled in when creating a data source item.
          readOnly: true
      additionalProperties: false
      discriminator:
        propertyName: type
        mapping:
          Text: '#/components/schemas/TextFieldSchema'
          Number: '#/components/schemas/NumberFieldSchema'
          Reference: '#/components/schemas/ReferenceFieldSchema'
          Image: '#/components/schemas/ImageFieldSchema'
          Language: '#/components/schemas/LanguageFieldSchema'
          Font: '#/components/schemas/FontFieldSchema'
          ColorTheme: '#/components/schemas/ColorThemeFieldSchema'
    CreateDataSourceRequest:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          pattern: ^[A-Z][a-zA-Z0-9_-]*$
          type: string
          description: The name of the data source. It must be unique. Max length is 100 characters.
        description:
          type:
          - string
          - 'null'
          description: The description of the data source.
        fields:
          type:
          - array
          - 'null'
          items:
            oneOf:
            - $ref: '#/components/schemas/CreateTextFieldSchemaRequest'
            - $ref: '#/components/schemas/CreateNumberFieldSchemaRequest'
            - $ref: '#/components/schemas/CreateImageFieldSchemaRequest'
            - $ref: '#/components/schemas/CreateReferenceFieldSchemaRequest'
            example:
              name: History
              type: text
              isMultipleLines: true
              defaultValue: The city was established in the year 1652 by Dutch explorers...
              isRequired: false
          description: The fields of the data source. If not specified, the data source will be created without fields.
      additionalProperties: false
      example:
        name: Cities
        description: Cities in which we have offices
        fields:
        - name: History
          type: text
          isMultipleLines: true
          defaultValue: The city was established in the year 1652 by Dutch explorers...
          isRequired: false
        - name: Population
          type: number
          defaultValue: 100222
          isRequired: true
        - name: Country
          type: reference
          referenceDataSourceId: '637989101951089955'
          defaultReferencedItemId: '638249311425155568'
          isRequired: true
        - name: Flag
          type: image
          isRequired: true
    Dependency:
      type: object
      properties:
        sourceEntityType:
          $ref: '#/components/schemas/SourceEntityType'
        sourceEntityId:
          type:
          - string
          - 'null'
          description: The id of the dependency source.
        description:
          type:
          - string
          - 'null'
          description: Human readable description of the source type.
      additionalProperties: false
      description: The model describing a dependency.
    CreateTextFieldSchemaRequest:
      allOf:
      - $ref: '#/components/schemas/CreateDataSourceFieldSchemaRequest'
      - type: object
        properties:
          isMultipleLines:
            type: boolean
            description: Whether the field is multiple lines. If true, the field will be rendered as a text area.
          defaultValue:
            type:
            - string
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
        additionalProperties: false
      example:
        name: History
        type: text
        isMultipleLines: true
        defaultValue: The city was established in the year 1652 by Dutch explorers...
        isRequired: false
    NumberFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - type: object
        properties:
          defaultValue:
            type:
            - number
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
            format: double
        additionalProperties: false
      example:
        id: 1
        name: NumberOfOffices
        type: number
        isRequired: true
        isLocked: false
        defaultValue: 1
    FontFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - type: object
        additionalProperties: false
      example:
        id: 5
        name: PreferredFont
        type: font
        isRequired: false
        isLocked: false
    TextFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - required:
        - isMultipleLines
        type: object
        properties:
          isMultipleLines:
            type: boolean
            description: Whether the field is multiple lines. If true, the field will be rendered as a text area.
          defaultValue:
            type:
            - string
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
        additionalProperties: false
      example:
        id: 1
        name: History
        type: text
        isRequired: true
        isLocked: false
        isMultipleLines: false
        defaultValue: The city was established in the year 1652 by Dutch explorers...
    NotFoundProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        traceId:
          type:
          - string
          - 'null'
      additionalProperties: false
      example:
        title: NotFound
        detail: The server can not find the requested resource.
        status: 404
        traceId: d61f7ce-cccb-4e5b-8727-3b68a61a0559
    CreateNumberFieldSchemaRequest:
      allOf:
      - $ref: '#/components/schemas/CreateDataSourceFieldSchemaRequest'
      - type: object
        properties:
          defaultValue:
            type:
            - number
            - 'null'
            description: The default value of the field. If specified, the field will be pre-filled with this value when creating a data source item.
            format: double
        additionalProperties: false
      example:
        name: Population
        type: number
        defaultValue: 100222
        isRequired: true
    ColorThemeFieldSchema:
      allOf:
      - $ref: '#/components/schemas/DataSourceFieldSchema'
      - type: object
        additionalProperties: false
      example:
        id: 6
        name: PreferredColourTheme
        type: colorTheme
        isRequired: false
        isLocked: false
    CreateImageFieldSchemaRequest:
      allOf:
      - $ref: '#/components/schemas/CreateDataSourceFieldSchemaRequest'
      - type: object
        additionalProperties: false
      example:
        name: Flag
        type: image
        isRequired: true
    CreateDataSourceFieldSchemaRequest:
      required:
      - name
      - type
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: Data source field schema type.
        name:
          minLength: 1
          pattern: ^[A-Z][a-zA-Z0-9_-]*$
          type: string
          description: The name of the field. It must be unique within the data source.
        isRequired:
          type: boolean
          description: Whether the field is required. If true, the field must be filled in when creating a data source item.
      additionalProperties: false
      discriminator:
        propertyName: type
        mapping:
          Text: '#/components/schemas/CreateTextFieldSchemaRequest'
          Number: '#/components/schemas/CreateNumberFieldSchemaRequest'
          Image: '#/components/schemas/CreateImageFieldSchemaRequest'
          Reference: '#/components/schemas/CreateReferenceFieldSchemaRequest'
      example:
        name: History
        type: text
        isMultipleLines: true
        defaultValue: The city was established in the year 1652 by Dutch explorers...
        isRequired: false
    SourceEntityType:
      enum:
      - dataSource
      - dataSourceItem
      - other
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key