openapi: 3.1.0
info:
  title: Citrix ShareFile REST API v3
  description: |
    The ShareFile v3 REST API provides programmatic access to items,
    folders, files, users, groups, shares, and accounts in a customer
    subdomain. The API uses a subset of the OData specification with
    entity URIs of the form /sf/v3/{Entity}({id}). Authentication uses
    OAuth 2.0 with multiple supported grant types (authorization code,
    password, SAML assertion exchange), returning Bearer access tokens
    scoped to a customer subdomain.
  version: "3.0.0"
  contact:
    name: ShareFile API Documentation
    url: https://api.sharefile.com/
servers:
  - url: https://{subdomain}.sf-api.com/sf/v3
    variables:
      subdomain:
        default: example
        description: ShareFile account subdomain
security:
  - bearerAuth: []
tags:
  - name: Items
  - name: Folders
  - name: Users
  - name: Groups
  - name: Shares
  - name: Accounts
  - name: Sessions
paths:
  /Sessions/Login:
    get:
      tags: [Sessions]
      summary: Authenticate (deprecated; prefer OAuth)
      operationId: sessionLogin
      responses:
        "200":
          description: Session
  /Items:
    get:
      tags: [Items]
      summary: List root-level items the user has access to
      operationId: getRootItem
      responses:
        "200":
          description: Item collection
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items: { $ref: "#/components/schemas/Item" }
  /Items({id}):
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Items]
      summary: Get an item by id
      operationId: getItem
      parameters:
        - in: query
          name: $select
          schema: { type: string }
        - in: query
          name: $expand
          schema: { type: string }
      responses:
        "200":
          description: An item
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Item" }
    patch:
      tags: [Items]
      summary: Update an item (rename, move)
      operationId: updateItem
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Item" }
      responses:
        "200":
          description: Updated item
    delete:
      tags: [Items]
      summary: Delete an item
      operationId: deleteItem
      parameters:
        - in: query
          name: singleversion
          schema: { type: boolean }
        - in: query
          name: forceSync
          schema: { type: boolean }
      responses:
        "204":
          description: Deleted
  /Items({id})/Children:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Items]
      summary: List child items of a folder
      operationId: getItemChildren
      parameters:
        - in: query
          name: includeDeleted
          schema: { type: boolean }
        - in: query
          name: $skip
          schema: { type: integer }
        - in: query
          name: $top
          schema: { type: integer }
      responses:
        "200":
          description: Child items
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items: { $ref: "#/components/schemas/Item" }
    post:
      tags: [Items]
      summary: Create a new folder or file metadata under a parent item
      operationId: createItem
      parameters:
        - in: query
          name: overwrite
          schema: { type: boolean }
        - in: query
          name: passthrough
          schema: { type: boolean }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Item" }
      responses:
        "201":
          description: Created item
  /Items({id})/Download:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Items]
      summary: Download an item's content
      operationId: downloadItem
      parameters:
        - in: query
          name: includeAllVersions
          schema: { type: boolean }
        - in: query
          name: redirect
          schema: { type: boolean }
      responses:
        "302":
          description: Redirect to a download URL
        "200":
          description: File content
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
  /Items({id})/Upload:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Items]
      summary: Request an upload specification for a parent folder
      operationId: requestUpload
      parameters:
        - in: query
          name: method
          schema:
            type: string
            enum: [standard, streamed, threaded]
        - in: query
          name: fileName
          schema: { type: string }
        - in: query
          name: fileSize
          schema: { type: integer }
        - in: query
          name: overwrite
          schema: { type: boolean }
      responses:
        "200":
          description: Upload specification
  /Users:
    get:
      tags: [Users]
      summary: List users in the account
      operationId: getUsers
      parameters:
        - in: query
          name: emailAddress
          schema: { type: string, format: email }
        - in: query
          name: $skip
          schema: { type: integer }
        - in: query
          name: $top
          schema: { type: integer }
      responses:
        "200":
          description: A page of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
    post:
      tags: [Users]
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/User" }
      responses:
        "201":
          description: Created user
  /Users({id}):
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Users]
      summary: Get a user
      operationId: getUser
      responses:
        "200":
          description: A user
    patch:
      tags: [Users]
      summary: Update a user
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/User" }
      responses:
        "200":
          description: Updated user
    delete:
      tags: [Users]
      summary: Delete a user
      operationId: deleteUser
      responses:
        "204":
          description: Deleted
  /Groups:
    get:
      tags: [Groups]
      summary: List groups in the account
      operationId: getGroups
      responses:
        "200":
          description: A page of groups
    post:
      tags: [Groups]
      summary: Create a group
      operationId: createGroup
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Group" }
      responses:
        "201":
          description: Created group
  /Groups({id}):
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Groups]
      summary: Get a group
      operationId: getGroup
      responses:
        "200":
          description: A group
    patch:
      tags: [Groups]
      summary: Update a group
      operationId: updateGroup
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Group" }
      responses:
        "200":
          description: Updated group
    delete:
      tags: [Groups]
      summary: Delete a group
      operationId: deleteGroup
      responses:
        "204":
          description: Deleted
  /Shares:
    get:
      tags: [Shares]
      summary: List shares
      operationId: getShares
      responses:
        "200":
          description: A page of shares
    post:
      tags: [Shares]
      summary: Create a share
      operationId: createShare
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Share" }
      responses:
        "201":
          description: Created share
  /Shares({id}):
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Shares]
      summary: Get a share
      operationId: getShare
      responses:
        "200":
          description: A share
    delete:
      tags: [Shares]
      summary: Delete a share
      operationId: deleteShare
      responses:
        "204":
          description: Deleted
  /Accounts:
    get:
      tags: [Accounts]
      summary: Get the current account information
      operationId: getCurrentAccount
      responses:
        "200":
          description: Account information
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2-Access-Token
  schemas:
    Item:
      type: object
      properties:
        Id: { type: string }
        Name: { type: string }
        FileName: { type: string }
        FileSizeInKB: { type: integer }
        FileSizeBytes: { type: integer }
        Hash: { type: string }
        Path: { type: string }
        CreatorFirstName: { type: string }
        CreatorLastName: { type: string }
        CreationDate: { type: string, format: date-time }
        ProgenyEditDate: { type: string, format: date-time }
        Description: { type: string }
        Parent:
          type: object
          properties:
            Id: { type: string }
        DiskSpaceLimit: { type: integer }
        IsHidden: { type: boolean }
        BandwidthLimitInMB: { type: integer }
        Owner:
          type: object
          properties:
            Id: { type: string }
        Zone:
          type: object
          properties:
            Id: { type: string }
        url: { type: string, format: uri }
    User:
      type: object
      properties:
        Id: { type: string }
        Email: { type: string, format: email }
        FirstName: { type: string }
        LastName: { type: string }
        Company: { type: string }
        FullName: { type: string }
        Roles:
          type: array
          items: { type: string }
        IsAdministrator: { type: boolean }
        IsEmployee: { type: boolean }
        IsConfirmed: { type: boolean }
        IsDisabled: { type: boolean }
        DefaultZone:
          type: object
          properties:
            Id: { type: string }
        url: { type: string, format: uri }
    Group:
      type: object
      properties:
        Id: { type: string }
        Name: { type: string }
        Account:
          type: object
          properties:
            Id: { type: string }
        Owner:
          type: object
          properties:
            Id: { type: string }
        Contacts:
          type: array
          items:
            type: object
            properties:
              Id: { type: string }
              Email: { type: string, format: email }
        IsShared: { type: boolean }
        NumberOfContacts: { type: integer }
        url: { type: string, format: uri }
    Share:
      type: object
      properties:
        Id: { type: string }
        ShareType:
          type: string
          enum: [Send, Receive]
        Title: { type: string }
        Items:
          type: array
          items:
            type: object
            properties:
              Id: { type: string }
        Recipients:
          type: array
          items:
            type: object
            properties:
              Id: { type: string }
              Email: { type: string, format: email }
        HasSentMessage: { type: boolean }
        SentMessageTitle: { type: string }
        IsViewOnly: { type: boolean }
        RequireLogin: { type: boolean }
        RequireUserInfo: { type: boolean }
        Creator:
          type: object
          properties:
            Id: { type: string }
        CreationDate: { type: string, format: date-time }
        ExpirationDate: { type: string, format: date-time }
        MaxDownloads: { type: integer }
        TotalDownloads: { type: integer }
        IsConsumed: { type: boolean }
        IsRead: { type: boolean }
        url: { type: string, format: uri }