Visier Projects API

openapi: 3.2.0
info:
  title: Visier Administration Projects API
  description: Visier APIs for managing your tenant or tenants in Visier. You can programmatically manage user accounts in Visier, the profiles and permissions assigned to users, and to make changes in projects and publish projects to production. Administrating tenant users can use administration APIs to manage their analytic tenants and consolidated analytics tenants.<br>**Note:** If you submit API requests for changes that cause a project to publish to production (such as assigning permissions to users or updating permissions), each request is individually published to production, resulting in hundreds or thousands of production versions. We recommend that you use the `ProjectID` request header to make changes in a project, if `ProjectID` is available for the API endpoint.
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 22222222.99201.3040
security:
- ApiKeyAuth: []
  BearerAuth: []
- ApiKeyAuth: []
  CookieAuth: []
- ApiKeyAuth: []
  OAuth2Auth: []
tags:
- name: Projects
  description: Create projects, publish projects, and retrieve project details.
paths:
  /v1/admin/projects:
    get:
      tags:
      - Projects
      summary: Retrieve a list of draft projects accessible to the user
      description: "Get a list of draft projects accessible to the requesting user in the tenant.\n\n A project is accessible if it is owned by the user or shared to the user."
      operationId: Projects_GetProjects
      parameters:
      - name: with
        in: query
        description: "The types of draft projects to include in the request response.\n * If empty, returns all the `Open` draft projects.\n * If `Open`, returns all Open draft projects.\n * If `Approval`, returns all draft projects in the approval stage. Changes cannot made in Approval projects.\n * If `Rejected`, returns all draft projects that have been rejected. Changes cannot be committed in Rejected projects.\n * If `Archived`, returns all draft projects that have been archived. Changes cannot be committed in Archived projects."
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: The number of projects to return per type. The maximum number of projects to retrieve per type is 1000. The default is 100.
        schema:
          type: integer
          format: int32
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.GetProjectsAPIResponseDTO'
    post:
      tags:
      - Projects
      summary: Create a new draft project
      description: Create a new draft project in the tenant.
      operationId: Projects_CreateProject
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/servicing.ProjectDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.ProjectDTO'
  /v1/admin/projects/{projectId}:
    get:
      tags:
      - Projects
      summary: Retrieve a draft project's information
      description: "Retrieve the details of an accessible draft project. You must know the ID of the project to retrieve its details. To retrieve draft project IDs, see `GET /v1/admin/projects`.\n\n A project is accessible if it is owned by the user or shared to the user."
      operationId: Projects_GetProject
      parameters:
      - name: projectId
        in: path
        description: The unique identifier of the draft project you want to retrieve.
        required: true
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.ProjectDTO'
    post:
      tags:
      - Projects
      summary: Perform an operation on a draft project
      description: "Perform operations on a draft project. The following operations are supported:\n * `commitAndPublish`: Commits project changes and publishes the project to production."
      operationId: Projects_RunProjectOperation
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/servicing.ProjectOperationRequestDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.ProjectOperationResponseDTO'
    delete:
      tags:
      - Projects
      summary: Delete a draft project
      description: Delete a draft project in the tenant. The project will first be archived if applicable.
      operationId: Projects_DeleteProject
      parameters:
      - name: projectId
        in: path
        description: The unique ID of the draft project to be deleted.
        required: true
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.ProjectDTO'
  /v1/admin/projects/{projectId}/commits:
    get:
      tags:
      - Projects
      summary: Retrieve a list of all committed changes in a project
      description: Retrieve the full list of all committed changes in a project.
      operationId: Projects_GetProjectCommits
      parameters:
      - name: projectId
        in: path
        description: The unique identifier of the draft project you want to retrieve the committed changes for.
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of committed changes to return. Default is 400.
        schema:
          type: integer
          format: int32
      - name: start
        in: query
        description: The starting index of the first committed change to return. Default is 0.
        schema:
          type: integer
          format: int32
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/servicing.ProjectCommitsAPIResponseDTO'
    put:
      tags:
      - Projects
      summary: Import committed changes into a project
      description: 'Import a ZIP file that contains a list of committed changes into a draft project. The file must be an export from `POST /v1/admin/production-versions`.

        Use this API after making changes in a development environment to copy the changes to a draft project in your production environment.'
      operationId: Projects_PutProjectCommits
      parameters:
      - name: projectId
        in: path
        required: true
        description: The unique identifier of the draft project you want to import committed changes into.
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/zip:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCommitsAPIResponseDTO'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    servicing.ProjectOperationRequestDTO:
      type: object
      properties:
        operation:
          enum:
          - unknown
          - commitAndPublish
          type: string
          description: "The operation to perform on a draft project. Valid values:\n * `commitAndPublish`: Commits the requesting user's changes and publishes the draft project to production."
          format: enum
    ProjectCommitsAPIResponseDTO:
      type: object
      properties:
        commits:
          type: array
          description: A list of committed changes in the project.
          items:
            $ref: '#/components/schemas/ProjectCommitDTO'
    ProjectCommitDTO:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the committed change.
        name:
          type: string
          description: An identifiable name of the committed change to display in Visier.
        description:
          type: string
          description: A description of the committed change.
    servicing.GetProjectsAPIResponseDTO:
      type: object
      properties:
        openProjects:
          type: array
          items:
            $ref: '#/components/schemas/servicing.ProjectDTO'
          description: A list of objects representing the accessible open projects for the user.
        approvalProjects:
          type: array
          items:
            $ref: '#/components/schemas/servicing.ProjectDTO'
          description: A list of objects representing the accessible approval projects for the user.
        rejectedProjects:
          type: array
          items:
            $ref: '#/components/schemas/servicing.ProjectDTO'
          description: A list of objects representing the accessible rejected projects for the user.
        archivedProjects:
          type: array
          items:
            $ref: '#/components/schemas/servicing.ProjectDTO'
          description: A list of objects representing the accessible archived projects for the user.
    servicing.CommitDTO:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the committed change.
        name:
          type: string
          description: An identifiable name of the committed change to display in Visier.
        description:
          type: string
          description: A description of the committed change.
    servicing.ProjectCommitsAPIResponseDTO:
      type: object
      properties:
        commits:
          type: array
          items:
            $ref: '#/components/schemas/servicing.CommitDTO'
          description: A list of committed changes in the project.
    servicing.ProjectOperationResponseDTO:
      type: object
      properties:
        commitAndPublish:
          allOf:
          - $ref: '#/components/schemas/servicing.CommitAndPublishOperationResponseDTO'
          description: The result of the `commitAndPublish` operation.
    servicing.ProjectDTO:
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the project. Omit when creating a new project.
        name:
          type: string
          description: An identifiable project name to display in Visier.
        description:
          type: string
          description: A description of the project.
        releaseVersion:
          type: string
          description: The release version of the project.
        ticketNumber:
          type: string
          description: The change management ticket number of the project.
        versionNumber:
          type: integer
          description: The version number of the project.
          format: int32
        capabilities:
          type: array
          items:
            enum:
            - canRead
            - canWrite
            - canShare
            - owner
            type: string
            format: enum
          description: "The current user's capabilities for the project. Users with `canWrite`, `canShare`, or `owner` capabilities can add and commit changes to the project.\n **canRead**: The project has been shared to the user with `View` access.\n **canWrite**: The project has been shared to the user with `Edit` access.\n **canShare**: The project has been shared to the user with `Share` access.\n **owner**: The user is the owner of the project.\n Omit when creating a new project."
        projectType:
          enum:
          - Standard
          - Prototype
          - UnknownType
          type: string
          description: The type of the project. Omit when creating a new project.
          format: enum
    servicing.CommitAndPublishOperationResponseDTO:
      type: object
      properties:
        publishedVersion:
          allOf:
          - $ref: '#/components/schemas/servicing.ProjectDTO'
          description: The project version that was published to production.
    Status:
      type: object
      properties:
        localizedMessage:
          type: string
          description: Localized error message describing the root cause of the error.
        code:
          type: string
          description: Error classification.
        message:
          type: string
          description: Not used.
        rci:
          type: string
          description: Optional root cause identifier.
        userError:
          type: boolean
          description: Indicates whether the error is a user error.
      description: The response structure for errors.
  securitySchemes:
    CookieAuth:
      type: apiKey
      name: VisierASIDToken
      in: cookie
    ApiKeyAuth:
      type: apiKey
      name: apikey
      in: header
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/auth/oauth2/authorize
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
        password:
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
x-tagGroups:
- name: administration
  tags:
  - Projects
  - ProductionVersions
  - UsersV3
  - UsersV2
  - UserGroupsV2
  - UsersV1
  - Profiles
  - Permissions
  - TenantsV2
  - TenantsV1
  - ConsolidatedAnalytics
  - Sources
  - SystemStatus
  - EmailDomains
  - EncryptionKeys
  - NetworkSubnets
  - SidecarSolutions
  - ReleaseVersionConfiguration
  - VeeConfiguration