Unqork Promotions API

openapi: 3.2.0
info:
  version: 1.0.0
  x-logo:
    url: https://developers.unqork.io/unqork-logo.png
    backgroundColor: '#FFFFFF'
  title: Unqork Customer Promotions API
  description: Unqork's customer REST API, based on open standards, allows you to set and retrieve module submission data, as well as control other aspects of your Unqork environment.
servers:
- url: https://{host}/api/1.0
  variables:
    host:
      default: env.unqork.io
      description: Environment host
security:
- OAuth2: []
tags:
- name: Promotions
  description: The following endpoints are available to "Administrator" users and users with the "Promote" permission for the resource.
paths:
  /promote/hosts:
    get:
      tags:
      - Promotions
      summary: Promotion Hosts
      operationId: getPromotionHosts
      description: 'Returns list of environments authorized for promotion

        ### Authorization Required:

        - Application Promote or Style Promote or Data Collections Promote'
      responses:
        '200':
          description: Hosts Loaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionHosts'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/module:
    post:
      tags:
      - Promotions
      summary: Promote Module
      operationId: promoteModule
      description: 'Promote a specific module

        ### Authorization Required:

        - Application Promote'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionModuleExecuteRequest'
      responses:
        '204':
          description: Job Executed
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/referenceData:
    post:
      tags:
      - Promotions
      summary: Promote Reference Data
      operationId: promoteDataCollection
      description: 'Promote a collection of reference data

        ### Authorization Required:

        - Data Collections Promote'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionReferenceDataExecuteRequest'
      responses:
        '204':
          description: Job Executed
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/applicationByItems:
    post:
      tags:
      - Promotions
      summary: Promote Application by items
      operationId: promoteApplicationByItems
      description: 'Promote a specific application with Modules, Workflows, Data Schemas, Data Collections, Module Archives, or Workflow Archives

        ### Authorization Required:

        - Application Promote'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionApplicationByItemExecuteRequest'
      responses:
        '200':
          description: Job Execution Initiated.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/style:
    post:
      tags:
      - Promotions
      summary: Promote Style
      operationId: promoteStyle
      description: 'Promote a specific Style

        ### Authorization Required:

        - Style Promote'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionStyleExecuteRequest'
      responses:
        '204':
          description: Job Executed
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/groups:
    post:
      tags:
      - Promotions
      summary: Promote Groups
      operationId: promoteGroups
      description: 'Promote specific groups or all groups

        ### Authorization Required:

        - Designer Administrator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionGroupExecuteRequest'
      responses:
        '204':
          description: Job Executed
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /promote/roles:
    post:
      tags:
      - Promotions
      summary: Promote Roles
      operationId: promoteRoles
      description: 'Promote all roles

        ### Authorization Required:

        - Designer Administrator'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromotionRoleExecuteRequest'
      responses:
        '204':
          description: Job Executed
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PromotionStyleExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      - styleName
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
        styleName:
          description: Style name of the style to promote
          type: string
    Error:
      type: object
      description: Error
      required:
      - code
      - message
      properties:
        code:
          description: HTTP status code
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
    PromotionReferenceDataExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      - collectionName
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
        collectionName:
          description: Name of the reference data collection to promote
          type: string
    PromotionModuleExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      - moduleId
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
        moduleId:
          description: ID of module to Promote
          type: string
    PromotionHosts:
      type: array
      items:
        type: object
        properties:
          clientName:
            type: string
            description: Target environment name
          clientLevel:
            type: string
            description: Level of the environment (qa, uat, production, etc.)
          isProduction:
            type: boolean
            description: 'Whether the host is a production environment or not

              NOTE: This will be true for preprod environments

              '
    PromotionGroupExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
        groupNames:
          description: Names of the groups to promote
          type: array
          items:
            type: string
    PromotionRoleExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
    PromotionApplicationByItemExecuteRequest:
      type: object
      required:
      - clientName
      - clientLevel
      - applicationId
      properties:
        clientName:
          type: string
          description: Target environment name
        clientLevel:
          type: string
          description: Level of the environment (qa, uat, production, etc.)
        applicationId:
          description: applicationId of the application to promote
          type: string
        modules:
          description: Array of Modules to Promote
          type: array
          items:
            type: string
          example:
          - moduleId1
          - moduleId2
        referenceDataCollections:
          description: Array of Reference Data Collections to Promote
          type: array
          items:
            type: string
          example:
          - collectionName1
          - collectionName2
        moduleArchives:
          description: 'Array of Module Archives to Promote. Must include the moduleId

            '
          type: array
          items:
            type: object
            required:
            - moduleId
            - archiveId
            properties:
              moduleId:
                type: string
                description: ID of the Module whose archive needs to be promoted
              archiveId:
                type: string
                description: Archive Id of the Module
            example:
              moduleId: moduleId
              archiveId: archiveId of the Module
        workflowArchives:
          description: Array of Workflow Archives to Promote
          type: array
          items:
            description: Archive Id of the Workflow
            type: string
          example:
          - workflowArchiveId1
          - workflowArchiveId2
        workflows:
          description: Array of Workflows to Promote
          type: array
          items:
            type: string
          example:
          - workflowId1
          - workflowId2
        dataSchemaIds:
          description: Array of Data Schemas to Promote
          type: array
          items:
            type: string
          example:
          - dataSchemaId1
          - dataSchemaId2
        dataModels:
          description: Array of Data Models to Promote
          type: array
          items:
            type: string
          example:
          - dataModelId1
          - dataModelId2
        schemas:
          description: Array of Data Model Schemas to Promote
          type: array
          items:
            type: string
          example:
          - schemaId1
          - schemaId2
        searchConfigs:
          description: Array of Queries to Promote
          type: array
          items:
            type: string
          example:
          - queryId1
          - queryId2
  securitySchemes:
    OAuth2:
      description: "The Unqork API implements the [OAuth 2.0 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) and the [OAuth 2.0 Password Grant](https://tools.ietf.org/html/rfc6749#section-1.3.3). Access via OAuth2 Client Credentials Grant can be utilized by creating Client Credentials through the API Access Management Administration page. Access via OAuth2 Password Grant can be enabled for all users in Environment Administration. Once OAuth2 Password Grant is enabled, all Unqork users can use their Unqork username/password to retrieve an access token.\n\nIn order to utilize any of the API resources, you must first retrieve an access token by POSTing your credentials to the access token URL, e.g. using `curl`:\n```\n  $ curl -u '{clientId}:{clientSecret}' -X POST --basic https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=client_credentials\"\n```\nOr:\n```\n  $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=password&username={username}&password={password}\"\n```\nThis returns an \"access_token\", which you would then retain and use in any subsequent resource requests. **Access tokens expire after one hour, at which point you must retrieve a new one.** The access token should be included in a request header:\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/api/1.0/{endpoint}\n```\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
        password:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A