openapi: 3.2.0
info:
  title: Tapis Files Post Its API
  description: The Tapis Files API provides for management of file resources on Tapis systems
  version: 1.8.2
  termsOfService: https://tapis-project.org
  contact:
    name: Files API - CICSupport
    url: https://tapis-project.org
    email: cicsupport@tacc.utexas.edu
  license:
    name: 3-Clause BSD License
    url: https://opensource.org/licenses/BSD-3-Clause
servers:
- url: http://localhost:8080/
  description: Local test environment
  variables: {}
- url: https://dev.develop.tapis.io/
  description: Development environment
  variables: {}
tags:
- name: PostIts
paths:
  /v3/files/postits/{systemId}/{path}:
    post:
      summary: Create a PostIt
      tags:
      - PostIts
      description: 'Create a PostIt. The PostIt will grant access to a file url.

        The newly created PostIt can be redeemed by anyone without

        further authorization. This will nearly identical to calling

        the files service getContents endpoint.'
      operationId: createPostIt
      security:
      - TapisJWT: []
      parameters:
      - name: systemId
        description: The name of the system to create the PostIt for.
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/IdString'
      - name: path
        in: path
        required: true
        description: Path relative to the system *rootDir*
        example: /DirectoryA/DirectoryB/file.txt
        schema:
          type: string
      requestBody:
        required: true
        description: A JSON document describing the PostIt to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostItRequest'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostItResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
  /v3/files/postits:
    get:
      summary: List PostIts
      tags:
      - PostIts
      description: 'Retrieve a list of all PostIts. Use *listType* and *select* query

        parameters to limit results. Query parameter *listType* allows for filtering

        results based on authorization. Options for *listType* are

        - *OWNED* Include only items owned by requester (Default)

        - *ALL* Include all items requester is authorized to view. (Tenant admins can view all PostIts in their tenant).'
      operationId: listPostIts
      security:
      - TapisJWT: []
      parameters:
      - name: listType
        in: query
        schema:
          $ref: '#/components/schemas/ListTypeEnum'
      - name: limit
        in: query
        description: Limit number of items returned. For example limit=10. Use -1 for unlimited. Default is 100.
        schema:
          type: integer
          default: 100
      - name: orderBy
        in: query
        description: Attribute for sorting. Direction may be included. For example orderBy=id(desc). Default direction is (asc).
        schema:
          type: string
      - name: skip
        in: query
        description: Number of items to skip. Use one of skip or startAfter. For example skip=10. Default is 0.
        schema:
          type: integer
      - name: startAfter
        in: query
        description: Where to start when sorting. Use one of skip or startAfter. Must also specify orderBy. For example, limit=10&orderBy=id(asc)&startAfter=<postitid>
        schema:
          type: string
      - name: select
        in: query
        description: List of attributes to be included as part of each result item. Keywords *allAttributes* and *summaryAttributes* are supported. For example select=id,owner,path
        schema:
          type: string
          default: summaryAttributes
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostItListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
  /v3/files/postits/{postitId}:
    get:
      summary: Get PostIt
      tags:
      - PostIts
      description: Get a single PostIt. This does not redeem the PostIt.
      operationId: getPostIt
      security:
      - TapisJWT: []
      parameters:
      - name: postitId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostItResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
    patch:
      summary: Modify a PostIt
      tags:
      - PostIts
      description: Update selected fields of a PostIt.
      operationId: updatePostIt
      security:
      - TapisJWT: []
      parameters:
      - name: postitId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        description: A JSON document describing the PostIt to be updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePostItRequest'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostItResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
    delete:
      summary: Delete a PostIt
      tags:
      - PostIts
      description: Delete a PostIt.
      operationId: deletePostIt
      security:
      - TapisJWT: []
      parameters:
      - name: postitId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespChangeCount'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '401':
          description: Not Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
  /v3/files/postits/redeem/{postitId}:
    get:
      summary: Redeem PostIt
      tags:
      - PostIts
      description: Redeem a PostIt. This will return the file that is pointed to by the PostIt. No authentication is required. If the *zip* query param is provided it controls if the content is zipped or not. If zip is not provided, it defaults to false unless the path pointed to by the PostIt is a directory. In the case of a directory, the default is zip=true. Directories must by redeemed in zipped format, so either accept the default, or specify zip=true.
      operationId: redeemPostIt
      parameters:
      - name: postitId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: zip
        in: query
        description: Indicates a zip output stream should be provided.  If zip is not provided it defaults to false unless the path is a directory.  In the case of a directory the content will be zipped.
        schema:
          type: boolean
        example: false
      - name: download
        in: query
        description: If set to true, this will force a browser to initiate a file download.  If set to false, the content-disposition header will be set to inline causing the browser to render the document.  If download is not provided it defaults to false.
        schema:
          type: boolean
        example: false
      responses:
        '200':
          description: Success.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '403':
          description: Permission Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileStringResponse'
components:
  schemas:
    PostItListResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/PostIt'
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        metadata:
          type: object
    ListTypeEnum:
      type: string
      default: OWNED
      enum:
      - OWNED
      - ALL
    UpdatePostItRequest:
      type: object
      properties:
        allowedUses:
          type: integer
          format: int32
          description: Number of times that the new PostIt can be redeemed.
        expiration:
          type: string
          format: date-time
          description: Expiration date of the PostIt.
        unlimited:
          type: boolean
          description: If set to true, this PostIt will have unlimited uses and not expire.
    FileStringResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        result:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        metadata:
          type: object
    RespChangeCount:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        result:
          $ref: '#/components/schemas/ResultChangeCount'
        metadata:
          type: object
    IdString:
      type: string
      minLength: 1
      maxLength: 80
    PostItResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        result:
          $ref: '#/components/schemas/PostIt'
        version:
          type: string
        commit:
          type: string
        build:
          type: string
        metadata:
          type: object
    ResultChangeCount:
      type: object
      properties:
        changes:
          type: integer
          format: int32
          example: 1
    PostIt:
      type: object
      properties:
        postitId:
          type: string
          format: uuid
          description: The unique ID of the PostIt.
        systemId:
          type: string
          description: The ID of the system where the file pointed to by the PostIt resides.
        owner:
          type: string
          description: The owner of the PostIt.
        tenantId:
          type: string
          description: the tenant that tthe PostIt belongs to.
        path:
          type: string
          description: Path relative to the system *rootDir*
        allowedUses:
          type: integer
          format: int32
          description: The number of times the PostIt may be redeemed.  This number minus *uses* is the number of uses remaining.
        timesUsed:
          type: integer
          format: int32
          description: The number of times the PostIt has already been retrieved.
        jwtUser:
          type: string
          description: Authenticated user from the JWT (may be different than OBO user).
        jwtTenantId:
          type: string
          description: Tenant of authenticated user from the JWT (may be different than OBO user's tenant).
        redeemUrl:
          type: string
          description: The url to use to retrieve the file pointed to by the PostIt.
        expiration:
          type: string
          format: date-time
          description: The expiration date/time of the PostIt.
        created:
          type: string
          format: date-time
          description: Creation timestamp in UTC
        updated:
          type: string
          format: date-time
          description: Last update timestamp in UTC
    CreatePostItRequest:
      type: object
      properties:
        allowedUses:
          type: integer
          format: int32
          description: 'Number of times that the new PostIt can be redeemed. The

            default is one use.  Setting the value to -1 (negative one)

            will allow the PostIt to be redeemed an unlimited number of

            times.

            '
          default: 1
        validSeconds:
          type: integer
          format: int32
          description: "Number of seconds until the PostIt expires.  \nDefault is 30 days.\n"
          default: 2592000
  securitySchemes:
    TapisJWT:
      type: apiKey
      description: Tapis signed JWT token authentication
      name: X-Tapis-Token
      in: header
externalDocs:
  description: Tapis Project
  url: https://tapis-project.org