swagger: '2.0'
info:
  description: Provides PUBLIC API functionality for Agile Documents REST API
  version: "2018.08.01"
  title: Agile Documents API
  # Dev Team API Lead
  contact: 
    email: JNadrowski@blueclarity.com

  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

# tags are used for organizing operations
tags:
- name: admins
  description: Secured admin-only calls
- name: developers
  description: Operations available to regular developers

paths:

  /GetTaskStatus:
    get:
      tags:
      - developers
      summary: gets information about a specified task
      operationId: getTaskStatus
      description: |
        By passing in the appropriate options, you can retrieve task information from the system
      produces:
      - application/json
      parameters:
      - in: query
        name: APIKey
        description: your assigned API Key
        required: true
        type: string
      - in: query
        name: TaskID
        description: The Task GUID to lookup
        required: true
        type: string
        format: uuid
      responses:
        200:
          description: task results matching criteria
          schema:
            {
              $ref: '#/definitions/TaskStatus'
            }
        404:
          description: invalid parameter(s)
        406:
          description: invalid parameter(s)
        500:
          description: exception
          
  /BuildWithURI:
    post:
      tags:
      - developers
      summary: queues a build of an Agile Document
      operationId: queueAgileDocumentBuild
      description: Adds an item to the system
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: query
        name: APIKey
        description: your assigned API Key
        required: true
        type: string
      - in: body
        name: AgileDocumentData
        description: Data that specifies the Agile Document and optionally data to augment the Agile Document build process.
        required: true
        schema:
          $ref: '#/definitions/AgileDocumentDataItem'
      responses:
        200:
          description: results from the queue request
          schema:
            {
              $ref: '#/definitions/BuildRequestResultItem'
            }
        404:
          description: invalid parameter(s)
        406:
          description: invalid parameter(s)
        500:
          description: exception

          
definitions:

  AgileDocumentDataItem:
    type: object
    required:
    - agiledocumentURI
    properties:
      agiledocumentURI:
        type: string
        format: url
        example: https://blueclarity.sharepoint.com/sites/site1/ADExamples/Word/EX1/EX1.AgileDocument.xml
        description: The Agile Document you wish to build.
      findinsertURI:
        type: string
        format: url
        example: https://blueclarity.sharepoint.com/sites/site1/CustomList/2_.000
        description: The Optional list item you wish to merge with the build. See https://www.blueclarity.com/AgileDocuments/Help/M_FindInsert for more information.
      addtoconditionalcontent:
        type: string
        example: key1, key2
        description: Comma seperated list of additional content keys to add to the Agile Document during the build.
      findinsertafter:
        type: string
        format: bool
        example: false
        description: If true, Find and Insert AFTER Insertion Point Construction.
      outputfileuri:
        type: string
        format: url
        example: Out/NewFile1
        description: The Agile Documents output file(s) will be stored at this new location. Agile Documents will add the appropriate extension depending on what output type was specified. Without this setting, the output will be stored as the combination of the Agile Document's output folder plus the Agile Document file name plus the appropriate file extension. This can be a relative URL (relative to the output folder specified in the Agile Document) or a valid absolute URL.
      outputfilesuffix:
        type: string
        format: url
        example: MySuffix
        description: The Agile Documents output file(s) will be appended with this suffix. Agile Documents will add the appropriate extension depending on what output type was specified. Please note that this can NOT be combined with AD_OutputFileUri.
      removeexistingconditionalcontent:
        type: string
        format: bool
        example: false
        description: If true, removes all the EXISTING Conditional Content Keys. This can be paired with AD_AddToConditionalContent so that only the keys specified in AD_AddToConditionalContent will be used.
      webhook:
        type: string
        format: url
        example: http://somewebhook.com/webhook1
        description:  Adds to the web hooks listed for the root Agile Document.
        
  BuildRequestResultItem:
    type: object
    required:
    - TaskID
    - AgileDocumentURI
    properties:
      TaskID:
        type: string
        format: uuid
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      AgileDocumentURI:
        type: string
        format: url
        example: https://blueclarity.sharepoint.com/sites/site1/ADExamples/Word/EX1/EX1.AgileDocument.xml
        
  TaskStatus:
    type: object
    required:
    - TaskID
    - Queued
    properties:
      TaskID:
        type: string
        format: uuid
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      Queued:
        type: string
        format: date-time
        example: 2016-08-29T09:12:33.001
      PercentComplete:
        type: string
        format: float
        example: 100.0
      Started:
        type: string
        format: date-time
        example: 2016-08-29T09:12:33.001
      LastServerUpdate:
        type: string
        format: date-time
        example: 2016-08-29T09:12:33.001
      IsException:
        type: boolean
        example: false
      IsCompleted:
        type: boolean
        example: true
      Outputs:
        type: array
        items: 
          $ref: '#/definitions/OutputItem'
          
  OutputItem:
    type: object
    required:
    - ListItemURI
    properties:
      Created:
        type: string
        format: date-time
        example: 2016-08-29T09:12:33.001
      ListItemURI:
        type: string
        format: url
        example:  https://blueclarity.sharepoint.com/sites/site1/ADExamples/Word/EX1/EX1.DOCX
      ListItemINT:
        type: integer
        format: int32
        example: 15
      ParentList:
        type: string
        format: uuid
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      ParentWeb:
        type: string
        format: url
        example:  https://blueclarity.sharepoint.com/sites/site1
        
# Added by API Auto Mocking Plugin
# Dev Host: blueclarityweb-dev.azurewebsites.net
# Production Host: www.blueclarity.com
host: www.blueclarity.com
basePath: /AgileDocuments/api/agiledocuments
schemes:
 - https