Emory University item API

openapi: 3.0.3
info:
  title: Girder REST API (Emory Digital Slide Archive) annotation item API
  version: 3.2.14
  description: OpenAPI 3.0 conversion of the Girder REST API powering the Emory Digital Slide Archive (computablebrain). Converted faithfully from the live Swagger 2.0 document at https://computablebrain.emory.edu/api/v1/describe.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
servers:
- url: https://computablebrain.emory.edu/api/v1
tags:
- description: item resource
  name: item
paths:
  /item:
    get:
      description: 'You must pass either a "folderId" or "text" field to specify how you are searching for items.  If you omit one of these parameters the request will fail and respond : "Invalid search mode."'
      operationId: item_find_item
      parameters:
      - name: folderId
        in: query
        required: false
        description: Pass this to list all items in a folder.
        schema:
          type: string
      - name: text
        in: query
        required: false
        description: Pass this to perform a full text search for items.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Pass to lookup an item by exact name match. Must pass folderId as well when using this.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Result set size limit.
        schema:
          type: integer
          format: int32
          default: 50
      - name: offset
        in: query
        required: false
        description: Offset into result set.
        schema:
          type: integer
          format: int32
          default: 0
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: lowerName
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Item'
                type: array
        '400':
          description: A parameter was invalid.
        '403':
          description: Read access was denied on the parent folder.
      summary: List or search for items.
      tags:
      - item
    post:
      operationId: item_createItem_post_item
      parameters:
      - name: folderId
        in: query
        required: true
        description: The ID of the parent folder.
        schema:
          type: string
      - name: name
        in: query
        required: true
        description: Name for the item.
        schema:
          type: string
      - name: description
        in: query
        required: false
        description: Description for the item.
        schema:
          type: string
          default: ''
      - name: reuseExisting
        in: query
        required: false
        description: Return existing item (by name) if it exists.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: A parameter was invalid.
        '403':
          description: Write access was denied on the parent folder.
      summary: Create a new item.
      tags:
      - item
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: A JSON object containing the metadata keys to add
  /item/query:
    get:
      operationId: item_getItemsByQuery_query
      parameters:
      - name: query
        in: query
        required: true
        description: Find items that match this Mongo query.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Result set size limit.
        schema:
          type: integer
          format: int32
          default: 50
      - name: offset
        in: query
        required: false
        description: Offset into result set.
        schema:
          type: integer
          format: int32
          default: 0
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: _id
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Item'
                type: array
        '400':
          description: A parameter was invalid.
      summary: List items that match a query.
      tags:
      - item
  /item/test/tiles:
    get:
      operationId: item_getTestTilesInfo_test_tiles
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Get test large image metadata.
      tags:
      - item
      parameters: []
  /item/test/tiles/zxy/{z}/{x}/{y}:
    get:
      operationId: item_getTestTile_test_tiles_zxy_z_x_y
      parameters:
      - name: z
        in: path
        required: true
        description: The layer number of the tile (0 is the most zoomed-out layer).
        schema:
          type: string
      - name: x
        in: path
        required: true
        description: The X coordinate of the tile (0 is the left side).
        schema:
          type: string
      - name: y
        in: path
        required: true
        description: The Y coordinate of the tile (0 is the top).
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Get a test large image tile.
      tags:
      - item
  /item/{id}:
    delete:
      operationId: item_deleteItem_delete_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Write access was denied for the item.
      summary: Delete an item by ID.
      tags:
      - item
    get:
      operationId: item_getItem_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get an item by ID.
      tags:
      - item
    put:
      operationId: item_updateItem_put_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Name for the item.
        schema:
          type: string
      - name: description
        in: query
        required: false
        description: Description for the item.
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: Pass this to move the item to a new folder.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: ID was invalid.
        '403':
          description: Write access was denied for the item or folder.
      summary: Edit an item or move it to another folder.
      tags:
      - item
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: A JSON object containing the metadata keys to add
  /item/{id}/adjacent_images:
    get:
      operationId: item_getPreviousAndNextImages_id_adjacent_images
      parameters:
      - name: id
        in: path
        required: true
        description: The current item ID
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: The (virtual) folder ID the image is located in
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '404':
          description: Image not found
      summary: Get the previous and next image in the same folder as the given item.
      tags:
      - item
  /item/{id}/aperio:
    delete:
      operationId: item_removeAperio_delete_id_aperio
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the annotation item
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Remove Aperio specific metadata from an item
      tags:
      - item
    get:
      operationId: item_findAperio_id_aperio
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the slide image item
        schema:
          type: string
      - name: tag
        in: query
        required: false
        description: Filter by the given tag string
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Result set size limit.
        schema:
          type: integer
          format: int32
          default: 50
      - name: offset
        in: query
        required: false
        description: Offset into result set.
        schema:
          type: integer
          format: int32
          default: 0
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: name
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Find Aperio annotation items associated with a slide image.
      tags:
      - item
    post:
      operationId: item_importDocument_post_id_aperio
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the item containing the annotation file
        schema:
          type: string
      - name: imageId
        in: query
        required: true
        description: The ID of the slide image
        schema:
          type: string
      - name: tag
        in: query
        required: false
        description: A searchable tag to store with the metadata
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Import an item as an Aperio annotation
      tags:
      - item
    put:
      operationId: item_modifyAperio_put_id_aperio
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the annotation file
        schema:
          type: string
      - name: tag
        in: query
        required: true
        description: A searchable tag to store with the metadata
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Set the tag associated with the annotation file
      tags:
      - item
  /item/{id}/copy:
    post:
      description: If no folderId parameter is specified, creates a copy of the item in its current containing folder.
      operationId: item_copyItem_post_id_copy
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the original item.
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: The ID of the parent folder.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Name for the new item.
        schema:
          type: string
      - name: description
        in: query
        required: false
        description: Description for the new item.
        schema:
          type: string
      - name: copyAnnotations
        in: query
        required: false
        description: Copy annotations when copying item (default true)
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: 'A parameter was invalid.


            ID was invalid.'
        '403':
          description: 'Read access was denied on the original item.


            Write access was denied on the parent folder.'
      summary: Copy an item.
      tags:
      - item
  /item/{id}/download:
    get:
      operationId: item_download_id_download
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Byte offset into the file.
        schema:
          type: integer
          format: int32
          default: 0
      - name: format
        in: query
        required: false
        description: If unspecified, items with one file are downloaded as that file, and other items are downloaded as a zip archive.  If 'zip', a zip archive is always sent.
        schema:
          type: string
      - name: contentDisposition
        in: query
        required: false
        description: Specify the Content-Disposition response header disposition-type value, only applied for single file items.
        schema:
          type: string
          enum:
          - inline
          - attachment
          default: attachment
      - name: extraParameters
        in: query
        required: false
        description: Arbitrary data to send along with the download request, only applied for single file items.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Download the contents of an item.
      tags:
      - item
  /item/{id}/files:
    get:
      operationId: item_getFiles_id_files
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Result set size limit.
        schema:
          type: integer
          format: int32
          default: 50
      - name: offset
        in: query
        required: false
        description: Offset into result set.
        schema:
          type: integer
          format: int32
          default: 0
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: name
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/File'
                type: array
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get the files within an item.
      tags:
      - item
  /item/{id}/metadata:
    delete:
      operationId: item_deleteMetadata_delete_id_metadata
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: 'ID was invalid.


            Invalid JSON passed in request body.


            Metadata key name was invalid.'
        '403':
          description: Write access was denied for the item.
      summary: Delete metadata fields on an item.
      tags:
      - item
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/string'
        required: true
        description: A JSON list containing the metadata fields to delete
    put:
      description: Set metadata fields to null in order to delete them.
      operationId: item_setMetadata_put_id_metadata
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: allowNull
        in: query
        required: false
        description: Whether "null" is allowed as a metadata value.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '400':
          description: 'ID was invalid.


            Invalid JSON passed in request body.


            Metadata key name was invalid.'
        '403':
          description: Write access was denied for the item.
      summary: Set metadata fields on an item.
      tags:
      - item
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/string'
        required: true
        description: A JSON object containing the metadata keys to add
  /item/{id}/next_image:
    get:
      operationId: item_getNextImage_id_next_image
      parameters:
      - name: id
        in: path
        required: true
        description: The current image ID
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: The (virtual) folder ID the image is located in
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '404':
          description: Image not found
      summary: Get the next image in the same folder as the given item.
      tags:
      - item
  /item/{id}/position:
    get:
      description: 'You must pass either a "folderId" or "text" field to specify how you are searching for items.  If you omit one of these parameters the request will fail and respond : "Invalid search mode."'
      operationId: item_findPosition_id_position
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: Pass this to list all items in a folder.
        schema:
          type: string
      - name: text
        in: query
        required: false
        description: Pass this to perform a full text search for items.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: Pass to lookup an item by exact name match. Must pass folderId as well when using this.
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: lowerName
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: Read access was denied on the parent folder.
      summary: Report the offset of an item in a list or search.
      tags:
      - item
  /item/{id}/previous_image:
    get:
      operationId: item_getPreviousImage_id_previous_image
      parameters:
      - name: id
        in: path
        required: true
        description: The current item ID
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: The (virtual) folder ID the image is located in
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '404':
          description: Image not found
      summary: Get the previous image in the same folder as the given item.
      tags:
      - item
  /item/{id}/rootpath:
    get:
      operationId: item_rootpath_id_rootpath
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get the path to the root of the item's hierarchy.
      tags:
      - item
  /item/{itemId}/internal_metadata/{key}:
    delete:
      operationId: item_deleteMetadataKey_delete_itemId_internal_metadata_key
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The metadata key to delete.
        schema:
          type: string
          default: meta
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Write access was denied for the item.
      summary: Delete a single internal metadata key on this item.
      tags:
      - item
    get:
      operationId: item_getMetadataKey_itemId_internal_metadata_key
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The metadata key to retrieve.
        schema:
          type: string
          default: meta
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get the value for a single internal metadata key on this item.
      tags:
      - item
    put:
      operationId: item_updateMetadataKey_put_itemId_internal_metadata_key
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The metadata key which should have a new value.                 The default key, "meta" is equivalent to the external metadata.                 Editing the "meta" key is equivalent to using PUT /item/{id}/metadata.
        schema:
          type: string
          default: meta
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Write access was denied for the item.
      summary: Overwrite the value for a single internal metadata key on this item.
      tags:
      - item
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/string'
        required: true
        description: The new value that should be written for the chosen metadata key
  /item/{itemId}/tiles:
    delete:
      operationId: item_deleteTiles_delete_itemId_tiles
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Remove a large image from this item.
      tags:
      - item
    get:
      operationId: item_getTilesInfo_itemId_tiles
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get large image metadata.
      tags:
      - item
    post:
      operationId: item_createTiles_post_itemId_tiles
      parameters:
      - name: itemId
        in: path
        required: true
        description: The source item.
        schema:
          type: string
      - name: fileId
        in: query
        required: false
        description: The source file containing the image.  Required if there is more than one file in the item.
        schema:
          type: string
      - name: force
        in: query
        required: false
        description: Always use a job to create the large image.
        schema:
          type: boolean
          default: false
      - name: notify
        in: query
        required: false
        description: If a job is required to create the large image, a nofication can be sent when it is complete.
        schema:
          type: boolean
          default: true
      - name: localJob
        in: query
        required: false
        description: If true, run as a local job; if false, run via the remote worker
        schema:
          type: boolean
      - name: tileSize
        in: query
        required: false
        description: Tile size
        schema:
          type: integer
          format: int32
          default: 256
      - name: compression
        in: query
        required: false
        description: Internal compression format
        schema:
          type: string
          enum:
          - none
          - jpeg
          - deflate
          - lzw
          - zstd
          - packbits
          - webp
          - jp2k
      - name: quality
        in: query
        required: false
        description: JPEG compression quality where 0 is small and 100 is highest quality
        schema:
          type: integer
          format: int32
          default: 90
      - name: level
        in: query
        required: false
        description: Compression level for deflate (zip) or zstd.
        schema:
          type: integer
          format: int32
      - name: predictor
        in: query
        required: false
        description: Predictor for deflate (zip) or lzw.
        schema:
          type: string
          enum:
          - none
          - horizontal
          - float
          - 'yes'
      - name: psnr
        in: query
        required: false
        description: JP2K compression target peak-signal-to-noise-ratio where 0 is lossless and otherwise higher numbers are higher quality
        schema:
          type: integer
          format: int32
      - name: cr
        in: query
        required: false
        description: JP2K target compression ratio where 1 is lossless
        schema:
          type: integer
          format: int32
      - name: concurrent
        in: query
        required: false
        description: Suggested number of maximum concurrent processes to use during conversion.  Values less than or equal to 0 use the number of logical cpus less that value.  Default is -2.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Create a large image for this item.
      tags:
      - item
  /item/{itemId}/tiles/bands:
    get:
      operationId: item_getBandInformation_itemId_tiles_bands
      parameters:
      - name: itemId
        in: path
        required: true
        description: The ID of the item.
        schema:
          type: string
      - name: frame
        in: query
        required: false
        description: For multiframe images, the 0-based frame number.  This is ignored on non-multiframe images.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read access was denied for the item.
      summary: Get band information for a large image item.
      tags:
      - item
  /item/{itemId}/tiles/convert:
    post:
      description: This can be used to make an item that is a different internal format than the original item.
      operationId: item_convertImage_post_itemId_tiles_convert
      parameters:
      - name: itemId
        in: path
        required: true
        description: The source item.
        schema:
          type: string
      - name: fileId
        in: query
        required: false
        description: The source file containing the image.  Required if there is more than one file in the item.
        schema:
          type: string
      - name: folderId
        in: query
        required: false
        description: The destination folder.
        schema:
          type: string
      - name: name
        in: query
        required: false
        description: A new name for the output item.
        schema:
          type: string
      - name: localJob
        in: query
        required: false
        description: If true, run as a local job; if false, run via the remote worker
        schema:
          type: boolean
      - name: tileSize
        in: query
        required: false
        description: Tile size
        schema:
          type: integer
          format: int32
          default: 256
      - name: onlyFrame
        in: query
        required: false
        description: Only convert a specific 0-based frame of a multiframe file.  If not specified, all frames are converted.
        schema:
          type: integer
          format: int32
      - name: format
        in: query
        required: false
        description: File format
        schema:
          type: string
          enum:
          - tiff
          - aperio
      - name: compression
        in: query
        required: false
        description: Internal compression format
        schema:
          type: string
          e

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emory/refs/heads/main/openapi/emory-item-api-openapi.yml