openapi-v2.yaml

swagger: "2.0"
info:
  description: TileDB Storage Platform REST API
  title: Tiledb Storage Platform API
  version: 1.4.0

produces:
  - application/json
consumes:
  - application/json

schemes:
  - http
  - https

basePath: /v2

securityDefinitions:
  BasicAuth:
    type: basic
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-TILEDB-REST-API-KEY
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: https://oauth2.tiledb.com/oauth2/authorize
    tokenUrl: https://oauth2.tiledb.com/oauth2/token
    scopes:
      read: Grants read access
      write: Grants write access
      admin: Grants read and write access to administrative information

security:
  - BasicAuth: []
  - ApiKeyAuth: []
  # Commented out beacause this breaks the python autogenerated client
  # It always sets the Bearer authorization header even when empty :/
  # - OAuth2: [read, write, admin]

definitions:
  AssetType:
    description: Asset types represented as TileDB arrays
    type: string
    enum:
      # Array
      - array
      # Notebook
      - notebook
      # Dashboard
      - dashboard
      # UDF
      - user_defined_function
      # ML Model
      - ml_model
      # Files
      - file
      # Task graphs
      - registered_task_graph
      # Groups
      - group
      # VCF
      - vcf
      # SOMA
      - soma
      # Point cloud
      - pointcloud
      # Biomedical imaging
      - bioimg
      # Geometry
      - geometry
      # Raster
      - raster
      # Vector search
      - vector_search

  Datatype:
    description: TileDB data type
    type: string
    enum:
      # 32-bit signed integer
      - INT32
      # 64-bit signed integer
      - INT64
      # 32-bit floating point value
      - FLOAT32
      # 64-bit floating point value
      - FLOAT64
      # Character
      - CHAR
      # 8-bit signed integer
      - INT8
      # 8-bit unsigned integer
      - UINT8
      # 16-bit signed integer
      - INT16
      # 16-bit unsigned integer
      - UINT16
      # 32-bit unsigned integer
      - UINT32
      # 64-bit unsigned integer
      - UINT64
      # ASCII string
      - STRING_ASCII
      # UTF-8 string
      - STRING_UTF8
      # UTF-16 string
      - STRING_UTF16
      # UTF-32 string
      - STRING_UTF32
      # UCS2 string
      - STRING_UCS2
      # UCS4 string
      - STRING_UCS4
      # This can be any datatype. Must store (type tag, value) pairs.
      - ANY
      # Datetime with year resolution
      - DATETIME_YEAR
      # Datetime with month resolution
      - DATETIME_MONTH
      # Datetime with week resolution
      - DATETIME_WEEK
      # Datetime with day resolution
      - DATETIME_DAY
      # Datetime with hour resolution
      - DATETIME_HR
      # Datetime with minute resolution
      - DATETIME_MIN
      # Datetime with second resolution
      - DATETIME_SEC
      # Datetime with millisecond resolution
      - DATETIME_MS
      # Datetime with microsecond resolution
      - DATETIME_US
      # Datetime with nanosecond resolution
      - DATETIME_NS
      # Datetime with picosecond resolution
      - DATETIME_PS
      # Datetime with femtosecond resolution
      - DATETIME_FS
      # Datetime with attosecond resolution
      - DATETIME_AS
      # Time with hour resolution
      - TIME_HR
      # Time with minute resolution
      - TIME_MIN
      # Time with second resolution
      - TIME_SEC
      # Time with millisecond resolution
      - TIME_MS
      # Time with microsecond resolution
      - TIME_US
      # Time with nanosecond resolution
      - TIME_NS
      # Time with picosecond resolution
      - TIME_PS
      # Time with femtosecond resolution
      - TIME_FS
      # Time with attosecond resolution
      - TIME_AS
      # 8-bit unsigned integer
      - BLOB
      # Boolean
      - BOOL

  Layout:
    description: Layout of array
    type: string
    enum:
      # Row-major layout
      - row-major
      # Column-major layout
      - col-major
      # Global-order layout
      - global-order
      # Unordered layout
      - unordered

  Querytype:
    description: Type of query
    type: string
    enum:
      # READ
      - READ
      # Write
      - WRITE

  Querystatus:
    description: Status of query
    type: string
    enum:
      # FAILED
      - FAILED
      # COMPLETED
      - COMPLETED
      # INPROGRESS
      - INPROGRESS
      # INCOMPLETE
      - INCOMPLETE
      # UNINITIALIZED
      - UNINITIALIZED

  DomainArray:
    description: Domain object for an array of each type
    type: object
    properties:
      int8:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: int8
      uint8:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: uint8
      int16:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: int16
      uint16:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: uint16
      int32:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: int32
      uint32:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: uint32
      int64:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: int64
      uint64:
        type: array
        x-omitempty: true
        items:
          type: integer
          format: uint64
      float32:
        type: array
        x-omitempty: true
        items:
          type: number
          format: float
      float64:
        type: array
        x-omitempty: true
        items:
          type: number
          format: double

  Array:
    description: Represents an open array
    type: object
    required:
      - queryType
      - uri
    properties:
      queryType:
        description: Array opened for query type
        $ref: "#/definitions/Querytype"
      uri:
        description: Array uri
        type: string
      endTimestamp:
        description: Ending timestamp (epoch milliseconds) array is opened at
        type: number
        format: uint64
        example: 1540471791873
      startTimestamp:
        description: Starting timestamp (epoch milliseconds) array is opened at
        type: number
        format: uint64
        example: 1540471791873
      arraySchemaLatest:
        description: Latest array schema
        $ref: "#/definitions/ArraySchema"
      arraySchemasAll:
        description: Array's schemas
        $ref: "#/definitions/ArraySchemaMap"
      arrayMetadata:
        description: Array's metadata
        $ref: "#/definitions/ArrayMetadata"
      nonEmptyDomain:
        description: Array's non empty domain
        $ref: "#/definitions/NonEmptyDomainList"
      arrayDirectory:
        description: Array directory (for reads)
        $ref: "#/definitions/ArrayDirectory"
      fragmentMetadataAll:
        description: metadata for all fragments (for reads)
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/FragmentMetadata"
      openedAtEndTimestamp:
        description: The ending timestamp that the array was last opened at
        type: number
        format: uint64


  FragmentMetadata:
    type: object
    description: Metadata of a fragment
    properties:
      fileSizes:
        description: The size of each attribute file
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      fileVarSizes:
        description: The size of each var attribute file
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      fileValiditySizes:
        description: The size of each validity attribute file
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      fragmentUri:
        description: The uri of the fragment this metadata belongs to
        type: string
      hasTimestamps:
        description: True if the fragment has timestamps
        type: boolean
      hasDeleteMeta:
        description: True if the fragment has delete metadata
        type: boolean
      sparseTileNum:
        description: The number of sparse tiles
        type: number
        format: uint64
      tileIndexBase:
        description: Used to track the tile index base between global order writes
        type: number
        format: uint64
      tileOffsets:
        description: Tile offsets in their attribute files
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint64
      tileVarOffsets:
        description: Variable tile offsets in their attribute files
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint64
      tileVarSizes:
        description: The sizes of the uncompressed variable tiles
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint64
      tileValidityOffsets:
        description: Validity tile offests in their attribute files
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint64
      tileMinBuffer:
        description: tile min buffers
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      tileMinVarBuffer:
        description: tile min buffers for var length data
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      tileMaxBuffer:
        description: tile max buffers
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      tileMaxVarBuffer:
        description: tile max buffers for var length data
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      tileSums:
        description: tile sum values
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      tileNullCounts:
        description: tile null count values
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint64
      fragmentMins:
        description: fragment min values
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      fragmentMaxs:
        description: fragment max values
        type: array
        x-omitempty: true
        items:
          type: array
          items:
            type: number
            format: uint8
      fragmentSums:
        description: fragment sum values
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      fragmentNullCounts:
        description: fragment null count values
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      version:
        description: the format version of this metadata
        type: integer
        format: uint32
      timestampRange:
        description: A pair of timestamps for fragment
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      lastTileCellNum:
        description: The number of cells in the last tile
        type: integer
        format: uint64
      nonEmptyDomain:
        description: The non empty domain of the fragment
        $ref: "#/definitions/NonEmptyDomainList"
      rtree:
        description: The RTree for the MBRs serialized as a blob
        type: string
        format: binary
      hasConsolidatedFooter:
        description: if the fragment metadata footer appears in a consolidated file
        type: boolean
      gtOffsets:
        description: The start offsets of the generic tiles stored in the metadata file
        $ref: "#/definitions/GenericTileOffsets"

  GenericTileOffsets:
    type: object
    description: Array directory (for reads)
    properties:
      rtree:
        description: RTree serialized as a blob
        type: number
        format: uint64
      tileOffsets:
        description: tile offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileVarOffsets:
        description: variable tile offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileVarSizes:
        description: sizes of the uncompressed variable tiles offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileValidityOffsets:
        description: tile validity offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileMinOffsets:
        description: min tile offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileMaxOffsets:
        description: max tile offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileSumOffsets:
        description: tile sum offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      tileNullCountOffsets:
        description: null count offsets
        type: array
        x-omitempty: true
        items:
          type: number
          format: uint64
      fragmentMinMaxSumNullCountOffset:
        description: fragment min/max/sum/nullcount offsets
        type: number
        format: uint64
      processedConditionsOffsets:
        description: processed conditions offsets
        type: number
        format: uint64

  ArrayDirectory:
    type: object
    description: Array directory (for reads)
    properties:
      unfilteredFragmentUris:
        description: fragment URIs
        type: array
        x-omitempty: true
        items:
          type: string
      consolidatedCommitUris:
        description: consolidated commit URI set
        type: array
        x-omitempty: true
        items:
          type: string
      arraySchemaUris:
        description: URIs of all the array schema files
        type: array
        x-omitempty: true
        items:
          type: string
      latestArraySchemaUri:
        description: latest array schema URI.
        type: string
      arrayMetaUrisToVacuum:
        description: the array metadata files to vacuum
        type: array
        x-omitempty: true
        items:
          type: string
      arrayMetaVacUrisToVacuum:
        description: the array metadata vac files to vacuum
        type: array
        x-omitempty: true
        items:
          type: string
      commitUrisToConsolidate:
        description: the commit files to consolidate
        type: array
        x-omitempty: true
        items:
          type: string
      commitUrisToVacuum:
        description: the commit files to vacuum
        type: array
        x-omitempty: true
        items:
          type: string
      consolidatedCommitUrisToVacuum:
        description: the consolidated commit files to vacuum
        type: array
        x-omitempty: true
        items:
          type: string
      fragmentMetaUris:
        description: the URIs of the consolidated fragment metadata files
        type: array
        x-omitempty: true
        items:
          type: string
      timestampStart:
        description: Only the files created after timestamp_start are listed
        type: number
        format: uint64
      timestampEnd:
        description: Only the files created before timestamp_end are listed
        type: number
        format: uint64
      arrayMetaUris:
        description: the timestamped filtered array metadata URIs, after removing the ones that need to be vacuumed and those that do not fall within
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/TimestampedURI"
      deleteAndUpdateTileLocation:
        description: the location of delete tiles
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/DeleteAndUpdateTileLocation"

  DeleteAndUpdateTileLocation:
    type: object
    description: the location of delete tiles
    properties:
      uri:
        description: the uri
        type: string
      conditionMarker:
        type: string
      offset:
        type: number
        format: uint64

  TimestampedURI:
    type: object
    description: the timestamped filtered array metadata URIs, after removing the ones that need to be vacuumed and those that do not fall within
    properties:
      uri:
        description: the uri
        type: string
      timestampStart:
        description: start of timestamp
        type: number
        format: uint64
      timestampEnd:
        description: end of timestamp
        type: number
        format: uint64

  ArraySchemaMap:
    type: object
    description: array's schemas
    properties:
      entries:
        description: List of array schemas entries
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArraySchemaEntry"

  ArraySchemaEntry:
    type: object
    description: key/value pair representing an array schema map entry
    properties:
      key:
        type: string
      value:
        $ref: "#/definitions/ArraySchema"

  NonEmptyDomainList:
    type: object
    description: object containing non empty domains
    properties:
      nonEmptyDomains:
        description: Array's non empty domain
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/NonEmptyDomain"

  NonEmptyDomain:
    type: object
    description: object representing a non-empty domain
    required:
      - nonEmptyDomain
      - isEmpty
    properties:
      nonEmptyDomain:
        description: Non Empty Domain of array
        $ref: "#/definitions/DomainArray"
      isEmpty:
        description: Is non-empty domain really empty?
        type: boolean
        example: False
      sizes:
        description: Number of elements in DomainArray for var length
        type: array
        items:
          type: integer
          format: uint64

  ArrayType:
    description: TileDB array type
    type: string
    enum:
      # Dense array
      - dense
      # Sparse array
      - sparse

  Attribute:
    description: Attribute of array
    type: object
    required:
      - name
      - type
      - filterPipeline
      - cellValNum
    properties:
      name:
        description: Attribute name
        type: string
        example: attribute1
      type:
        $ref: "#/definitions/Datatype"
      filterPipeline:
        $ref: "#/definitions/FilterPipeline"
      cellValNum:
        description: Attribute number of values per cell
        type: integer
        example: 1
      nullable:
        description: Is attribute nullable
        type: boolean
        example: true
      fillValueValidity:
        description: Default validity fill value for nullable attributes
        type: boolean
        example: true
      fillValue:
        description: The default fill value
        type: array
        items:
          type: integer
          format: uint8

  FilterType:
    description: TileDB filter types
    type: string
    enum:
      # No-op filter
      - FILTER_NONE
      # Gzip compressor
      - FILTER_GZIP
      # Zstandard compressor
      - FILTER_ZSTD
      # LZ4 compressor
      - FILTER_LZ4
      # Run-length encoding compressor
      - FILTER_RLE
      # Bzip2 compressor
      - FILTER_BZIP2
      # Double-delta compressor
      - FILTER_DOUBLE_DELTA
      # Bit width reduction filter.
      - FILTER_BIT_WIDTH_REDUCTION
      # Bitshuffle filter.
      - FILTER_BITSHUFFLE
      # Byteshuffle filter.
      - FILTER_BYTESHUFFLE
      # Positive-delta encoding filter.
      - FILTER_POSITIVE_DELTA
      # Scale-float filter
      - FILTER_SCALE_FLOAT
      # Webp filter
      - FILTER_WEBP
      # CHECKSUM_MD5 filter
      - FILTER_CHECKSUM_MD5
      # CHECKSUM_SHA256 filter
      - FILTER_CHECKSUM_SHA256
      # DICTIONARY filter
      - FILTER_DICTIONARY

  Filter:
      description: Filter
      type: object
      required:
        - type
      properties:
        type:
          description: Filter type
          $ref: "#/definitions/FilterType"
        floatScaleConfig:
          description: Filter type
          $ref: "#/definitions/FloatScaleConfig"
        data:
          description: Filter data
          type: object
          properties:
            text:
              type: string
            bytes:
              type: array
              items:
                type: integer
                format: uint8
            int8:
              type: integer
              format: int8
            uint8:
              type: integer
              format: uint8
            int16:
              type: integer
              format: int16
            uint16:
              type: integer
              format: uint16
            int32:
              type: integer
              format: int32
            uint32:
              type: integer
              format: uint32
            int64:
              type: integer
              format: int64
            uint64:
              type: integer
              format: uint64
            float32:
              type: integer
              format: float
            float64:
              type: integer
              format: double

  FloatScaleConfig:
    description: FloatScaleConfig
    type: object
    properties:
      scale:
        type: integer
        format: double
      offset:
        type: integer
        format: double
      byteWidth:
        type: integer
        format: uint64

  FilterPipeline:
    description: One or more filters to apply
    type: object
    properties:
      filters:
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Filter"

  Dimension:
    description: Dimension of array
    type: object
    required:
      - type
      - domain
      - nullTileExtent
    properties:
      name:
        description: Dimension name
        type: string
        example: "row"
      type:
        $ref: "#/definitions/Datatype"
      domain:
        description: extent of domain
        $ref: "#/definitions/DomainArray"
      nullTileExtent:
        description: Is tile extent null
        type: boolean
        example: true
      tileExtent:
        description: Extent of tile
        type: object
        properties:
          int8:
            type: integer
            format: int8
          uint8:
            type: integer
            format: uint8
          int16:
            type: integer
            format: int16
          uint16:
            type: integer
            format: uint16
          int32:
            type: integer
            format: int32
          uint32:
            type: integer
            format: uint32
          int64:
            type: integer
            format: int64
          uint64:
            type: integer
            format: uint64
          float32:
            type: integer
            format: float
          float64:
            type: integer
            format: double
      filterPipeline:
        x-omit-empty: true
        $ref: "#/definitions/FilterPipeline"

  Domain:
    description: Domain of array
    type: object
    required:
      - type
      - tileOrder
      - cellOrder
      - dimensions
    properties:
      type:
        $ref: "#/definitions/Datatype"
        description: Domain Type
      tileOrder:
        $ref: "#/definitions/Layout"
        description: Tile Order
      cellOrder:
        $ref: "#/definitions/Layout"
        description: Cell Order
      dimensions:
        type: array
        description: Array of dimensions
        items:
          $ref: "#/definitions/Dimension"

  ArraySchema:
    description: ArraySchema during creation or retrieval
    type: object
    required:
      - version
      - arrayType
      - tileOrder
      - cellOrder
      - capacity
      - coordsFilterPipeline
      - offsetFilterPipeline
      - domain
      - attributes
    properties:
      uri:
        description: URI of schema
        type: string
        example: "s3://<bucket>/test_array"
      name:
        description: name of schema
        type: string
      version:
        description: file format version
        type: array
        x-omitempty: true
        items:
          type: integer
        example: [1, 3, 0]
      arrayType:
        $ref: "#/definitions/ArrayType"
        description: Type of array
        example: sparse
      tileOrder:
        description: Tile order setting of array
        $ref: "#/definitions/Layout"
        example: row-major
      cellOrder:
        description: Order of cells
        $ref: "#/definitions/Layout"
        example: row-major
      capacity:
        description: Capacity of array
        type: integer
        format: uint64
        example: 100000
      coordsFilterPipeline:
        description: Filter pipeline used for coordinates (enum)
        $ref: "#/definitions/FilterPipeline"
      offsetFilterPipeline:
        description: Filter pipeline use for variable offsets (enum)
        $ref: "#/definitions/FilterPipeline"
      validityFilterPipeline:
        description: Type of compression for validity buffers (enum)
        $ref: "#/definitions/FilterPipeline"
      domain:
        description: Domain of array
        $ref: "#/definitions/Domain"
      attributes:
        description: Attributes of array
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Attribute"
      allowsDuplicates:
        description: True if the array allows coordinate duplicates. Applicable only to sparse arrays.
        type: boolean
      timestampRange:
        description: The list of sizes per range
        type: array
        items:
          type: integer
          format: uint64

  ArrayMetadataEntry:
    type: object
    description: key/value pair representing an array metadata map entry
    properties:
      key:
        type: string
      type:
        type: string
      valueNum:
        type: integer
        format: uint32
      value:
        type: array
        items:
          type: integer
          format: uint8
      del:
        type: boolean

  ArrayMetadata:
    type: object
    description: user's TileDB array metadata
    properties:
      entries:
        description: List of metadata entries
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayMetadataEntry"

  AttributeBufferHeader:
    description: Represents an attribute buffer header information
    type: object
    required:
      - name
      - fixedLenBufferSizeInBytes
      - varLenBufferSizeInBytes

    properties:
      name:
        description: Attribute name
        type: string
        example: "attribute1"
      fixedLenBufferSizeInBytes:
        description: Number of bytes in the fixed-length attribute data buffer (offsets for var-len attributes)
        type: integer
        format: uint64
      varLenBufferSizeInBytes:
        description: Number of bytes in the var-length attribute data buffer
        type: integer
        format: uint64
      validityLenBufferSizeInBytes:
        description: Number of bytes for validity in case attribute is nullable
        type: integer
        format: uint64
      originalFixedLenBufferSizeInBytes:
        description: Original user set number of bytes in the fixed-length attribute data buffer
        type: integer
        format: uint64
      originalVarLenBufferSizeInBytes:
        description: Original user set number of bytes in the var-length attribute data buffer
        type: integer
        format: uint64
      originalValidityLenBufferSizeInBytes:
        description: Original user set number of bytes in the validity data buffer
        type: integer
        format: uint64

  Writer:
    type: object
    properties:
      checkCoordDups:
        type: boolean
      checkCoordOOB:
        type: boolean
      dedupCoords:
        type: boolean
      subarrayRanges:
        $ref: "#/definitions/Subarray"
      subarray:
        $ref: "#/definitions/DomainArray"

  SubarrayRanges:
    description: A set of 1D ranges for a subarray
    type: object
    properties:
      type:
        $ref: "#/definitions/Datatype"
      hasDefaultRange:
        description: True if the range is the default range
        type: boolean
      buffer:
        description: The bytes of the ranges
        type: array
        items:
          type: integer
          format: uint8
      bufferSizes:
        description: The list of sizes per range
        type: array
        items:
          type: integer
          format: uint64
      bufferStartSizes:
        description: The list of start sizes per range
        type: array
        items:
          type: integer
          format: uint64

  Subarray:
    description: A Subarray
    type: object
    properties:
      layout:
        $ref: "#/definitions/Layout"
      ranges:
        description: List of 1D ranges, one per dimension
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/SubarrayRanges"

  SubarrayPartitioner:
    description: The subarray partitioner
    type: object
    properties:
      subarray:
        $ref: "#/definitions/Subarray"
      budget:
        description: Result size budget (in bytes) for all attributes.
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/AttributeBufferSize"
      current:
        description: The current partition info
        type: object
        properties:
          subarray:
            $ref: "#/definitions/Subarray"
          start:
            description: PartitionInfo start
            type: integer
            format: uint64
          end:
            description: PartitionInfo end
            type: integer
            format: uint64
          splitMultiRange:
            description: PartitionInfo splitMultiRange
            type: boolean
      state:
        description: The state information for the remaining partitions to be produced
        type: object
        properties:
          start:
            description: State start
            type: integer
            format: uint64
          end:
            description: State end
            type: integer
            format: uint64
          singleRange:
            description: State singleRange
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/Subarray"
          multiRange:
            description: State multiRange
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/Subarray"
      memoryBudget:
        description: The memory budget for the fixed-sized attributes and the offsets of the var-sized attributes
        type: integer
        format: uint64
      memoryBudgetVar:
        description: The memory budget for the var-sized attributes
        type: integer
        format: uint64

  ReadState:
    description: state for reads
    type: object
    properties:
      initialized:
        description: True if the reader has been initialized.
        type: boolean

      overflowed:
        description: True if the query produced results that could not fit in some buffer.
        type: boolean

      unsplittable:
        description: True if the current subarray partition is unsplittable.
        type: boolean

      subarrayPartitioner:
        $ref: "#/definitions/SubarrayPartitioner"

  QueryReader:
    description: Read struct (can't be called reader due to class name conflict)
    type: object
    properties:
      layout:
        $ref: "#/definitions/Layout"
      subarray:
        $ref: "#/definitions/Subarray"
      readState:
        description: To handle incomplete read queries.
        $ref: "#/definitions/ReadState"

  Query:
    type: object
    required:
      - type
      - attributeBufferHeaders
      - layout
      - status
      - array
      - totalFixedLengthBufferBytes
      - totalVarLenBufferBytes
    properties:
      type:
        $ref: "#/definitions/Querytype"
      layout:
        $ref: "#/definitions/Layout"
      status:
        $ref: "#/definitions/Querystatus"
      attributeBufferHeaders:
        description: List of attribute buffer headers
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/AttributeBufferHeader"
      writer:
        description: writer contains data needed for continuation of global write order queries
        $ref: "#/definitions/Writer"
      reader:
        description: reader contains data needed for continuation of reads
        $ref: "#/definitions/QueryReader"
      array:
        description: Represents an open array
        $ref: "#/definitions/Array"
      totalFixedLengthBufferBytes:
        description: Total number of bytes in fixed size attribute buffers.
        type: integer
        format: uint64
      totalVarLenBufferBytes:
        description: Total number of bytes in variable size attribute buffers.
        type: integer
        format: uint64
      totalValidityBufferBytes:
        description: Total number of bytes in validity buffers
        type: integer
        format: uint64
    x-go-type:
      import:
        package: "github.com/TileDB-Inc/TileDB-Go"
        alias: "tiledb"
      type: "Query"

  AttributeBufferSize:
    type: object
    description: object representing buffer size of an attribute
    required:
      - attribute
      - offsetBytes
      - dataBytes
    properties:
      attribute:
        description: name of attribute
        type: string
      offsetBytes:
        description: buffer size (in bytes) of offset buffer
        type: integer
        format: uint64
      dataBytes:
        description: buffer size (in bytes) of data buffer
        type: integer
        format: uint64

  AssetActivityLog:
    type: object
    properties:
      id:
        type: string
        description: The ID of the activity
      event_at:
        description: time event took place (RFC3339)
        type: string
        format: date-time
      action:
        type: string
        description: type of the event
      username:
        description: User who performed action
        type: string
      array_task_id:
            description: uuid of associated array task
            type: string
      asset:
        description: The asset details
        type: object
        properties:
          id:
            description: The asset ID
            type: string
          name:
            description: The asset name
            type: string
          namespace:
            description: The namespace that the asset belongs to
            type: string
          asset_type:
            description: The type of the asset
            $ref: "#/definitions/AssetType"
    required:
      - id
      - event_at
      - action
      - username
      - asset

  ArrayActivityLog:
    description: Activity of an Array
    type: object
    properties:
      event_at:
        description: time event took place (RFC3339)
        type: string
        format: date-time
      action:
        description: Type of the event
        $ref: "#/definitions/ActivityEventType"
      username:
        description: User who performed action
        type: string
        example: "user1"
      bytes_sent:
        description: Bytes sent to client
        type: integer
        format: uint64
        example: 1073741824
      bytes_received:
        description: Bytes recieved from client
        type: integer
        format: uint64
        example: 1073741824
      array_task_id:
        description: uuid of associated array task
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      id:
        description: id of the activity
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      query_ranges:
        description: ranges for query
        x-omitempty: true
        type: string
        example: '{"rows":[{"start": 1, "end": 1},{"start": 3, "end": 4}],"cols":[{"start": 1, "end": 4}]}'
      query_stats:
        description: stats for query
        x-omitempty: true
        type: string
        example: '{"timers": {"Context.StorageManager.read_load_array_schema_from_uri.sum": 0.0255293, "...": "..."}, "counters": {"Context.StorageManager.read_unfiltered_byte_num": 191, "...": "..."}}'

  ActivityEventType:
    description: Type of activity logged
    type: string
    enum:
      # read_schema operation
      - read_schema
      # max_buffer_sizes operation
      - max_buffer_sizes
      # non_empty_domain operation
      - non_empty_domain
      # query read operation
      - query_read
      # query write operation
      - query_write
      # create operation
      - create
      # delete operation
      - delete
      # register operation
      - register
      # deregister operation
      - deregister
      # udf operations
      - udf
      # get array metadata operation
      - array_metadata_get
      # update array metadata operation
      - array_metadata_update
      # estimated_result_sizes
      - estimated_result_sizes
      # captures enum value "update" (registered UDFs)
      - update
      # captures enum value "info" (registered UDFs)
      - info
      # captures enum value "run" (registered UDFs)
      - run

  ArrayActivityLogData:
    description: Object including array tasks and metadata
    type: object
    properties:
      activitylogs:
        description: Array ArrayActivityLog
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActivityLog"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  PaginationMetadata:
    properties:
      page:
        description: pagination offset. Use it to skip the first ((page - 1) * per_page) items
        type: number
        format: uint64
        example: 1
      per_page:
        description: pagination limit (page size)
        type: number
        format: uint64
        example: 10
      total_pages:
        description: number of total pages with current limit
        type: number
        format: uint64
        example: 14
      total_items:
        description: number of total available items
        type: number
        format: uint64
        example: 138

  Error:
    type: object
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string
      request_id:
        type: string

  AccessCredentialType:
    description: "The types of an access credential"
    type: "string"
    enum:
      - "key" # a pair of (key, secret) values
      - "arn" # a role assignment
      - "token" # a token credential
      - "azure_token" # alias for "token" credential

  AccessCredential:
    # Within this type, all fields which are used to contain credential data
    # are tagged with `cred_field`.
    description: "A union type which may contain a credential to access any one cloud provider."
    type: "object"
    properties:
      uuid:
        description: The UUID of the credential
        type: string
      name:
        description: "A user-specified name for the key"
        type: string
      provider:
        description: "The service provider that this credential provides access to. This is derived from the one field which is set when creating or updating the credential data."
        $ref: "#/definitions/CloudProvider"
        readOnly: true
      provider_default:
        description: "True if this is the namespace's default credential to be used when connecting to the given cloud provider. There can be at most one default for each unique provider."
        type: boolean
        x-nullable: true
      created_at:
        description: "Time when the credential was created (rfc3339)"
        type: string
        format: date-time
        readOnly: true
      updated_at:
        description: "Time when the credential was last updated (rfc3339)"
        type: string
        format: date-time
        readOnly: true
      allowed_in_tasks:
        description: "Is this credential allowed to be used in tasks"
        type: boolean
        x-nullable: true
      credential:
        description: "The credential information itself. Exactly one sub-field may be set. The names match those in the CloudProvider enum."
        type: object
        x-omitempty: true
        x-go-custom-tag: 'tdbrest:"cred_field"'
        properties:
          aws:
            $ref: "#/definitions/AWSCredential"
          azure:
            $ref: "#/definitions/AzureCredential"
          gcp:
            $ref: "#/definitions/GCPInteroperabilityCredential"
      role:
        description: "The role information itself. Exactly one sub-field may be set. The names match those in the CloudProvider enum."
        type: object
        x-omitempty: true
        x-go-custom-tag: 'tdbrest:"cred_field"'
        properties:
          aws:
            $ref: "#/definitions/AWSRole"
      token:
        description: "The token information itself. Exactly one sub-field may be set. The names match those in the CloudProvider enum."
        type: object
        x-omitempty: true
        x-go-custom-tag: 'tdbrest:"cred_field"'
        properties:
          azure:
            $ref: "#/definitions/AzureToken"
          gcp:
            $ref: "#/definitions/GCPServiceAccountKey"

  AccessCredentialsData:
    description: Object including credentials and pagination metadata
    type: object
    properties:
      credentials:
        description: List of credentials
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/AccessCredential"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  AWSCredential:
    description: "Credential information to access Amazon Web Services"
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      access_key_id:
        description: "The ID of the access key"
        type: string
        x-go-custom-tag: 'tdbrest:"key_id" validate:"required"'
      secret_access_key:
        description: "The access key's secret. Never returned in responses."
        type: string
        x-go-custom-tag: 'tdbrest:"secret" validate:"required"'

      endpoint:
        description: "The endpoint used for this credential"
        x-nullable: true
        type: string
        example: "https://example.us-west-2.amazonaws.com"

  AzureCredential:
    description: "Credential information to access Microsoft Azure. Each supported property is the snake_case version of its name in an Azure Storage connection string."
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      account_name:
        description: "The name of the Azure account to access"
        type: string
        x-go-custom-tag: 'tdbrest:"key_id" validate:"required"'
      account_key:
        description: "The secret key. Never returned in responses."
        type: string
        x-go-custom-tag: 'tdbrest:"secret" validate:"required"'

  GCPInteroperabilityCredential:
    description: "Credential information to access Google Cloud. using well knows key/secret pair to access storage."
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      access_key_id:
        description: "The ID of the access key"
        type: string
        x-go-custom-tag: 'validate:"required"'
      secret_access_key:
        description: "The access key's secret. Never returned in responses."
        type: string
        x-go-custom-tag: 'tdbrest:"secret" validate:"required"'

  AWSRole:
    description: "Role information to access Amazon Web Services"
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      role_arn:
        description: "The role arn used to access"
        x-go-name: "RoleARN"
        type: string
        x-go-custom-tag: 'validate:"required" tdbrest:"key_id,limit_20"'
        example: arn:partition:service:region:account-id:resource-type:resource-id
      external_id:
        description: "The role external id used to access"
        x-go-custom-tag: 'validate:"required" tdbrest:"secret"'
        x-go-name: "RoleExternalID"
        type: string
        example: "MzU0M2UwMTItMWJhYy00NWUwLThmZDItZTgwYmQ1NjE5Yjhm"
      endpoint:
        x-nullable: true
        description: "The endpoint used for this role"
        type: string
        example: "https://example.us-west-2.amazonaws.com"

  AzureToken:
    description: "Token information to access Azure services"
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      account_name:
        description: "The account name of the configuration"
        x-go-name: "AccountName"
        type: string
        x-go-custom-tag: 'validate:"required"'
        example: tiledbpoc
      sas_token:
        x-nullable: false
        description: "The token to use for this account"
        type: string
        example: "sv=2022-11-02&ss=bfqt&srt=sco&sp=dsafdssdfafasdfsda&se=2024-03-28T03:02:08Z&st=2024-03-27T19:02:08Z&spr=https&sig=444444555555555555555555555555555555555%3D"

  GCPServiceAccountKey:
    description: The key to a Google Cloud Platform service account.
    type: object
    x-nullable: true
    x-omitempty: true
    properties:
      account_id:
        description: |
          The ID of the service account (i.e., its email address).

          This is ignored when uploading key information, and is only provided
          by the server when downloading metadata about an existing key.
        type: string
        x-go-custom-tag: 'tdbrest:"key_id,output_only"'
        example: "identity-data-reader@cinco-research.iam.gserviceaccount.com"
      key_id:
        description: |
          The ID of the particular key. This identifies it among other keys
          issued for this service account.

          This is ignored when uploading key information, and is only provided
          by the server when downloading metadata about an existing key.
        type: string
        x-go-custom-tag: 'tdbrest:"output_only"'
        example: "b85b7bac16fabf44fd9cd6885d4d1b444f07e9ab"
      key_text:
        description: |
          The full file provided by Google Cloud. This is usually in the form of
          a JSON document, but TileDB Cloud treats it as opaque (except to
          attempt to extract the service account ID and the key ID).
        type: string
        x-go-custom-tag: 'tdbrest:"secret"'
        example: |
          {
            "type": "service_account",
            "project_id": "cinco-research",
            "private_key_id": "b85b7bac16fabf44fd9cd6885d4d1b444f07e9ab",
            "private_key": "-----BEGIN PRIVATE KEY-----\n[lots of data goes here]\n-----END PRIVATE KEY-----\n",
            "client_email": "identity-data-reader@cinco-research.iam.gserviceaccount.com",
            "client_id": "105800434159734259879",
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
            "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
            "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/identity-data-reader%40cinco-research.iam.gserviceaccount.com",
            "universe_domain": "googleapis.com"
          }


  CloudProvider:
    description: "A service where data is stored or computations take place."
    type: "string"
    enum:
      - "AWS" # Amazon Web Services
      - "AZURE" # Microsoft Azure
      - "GCP" # Google Cloud Platform

  MetadataEntry:
    type: object
    description: key/value pair representing a group metadata map entry
    properties:
      key:
        type: string
      type:
        type: string
      valueNum:
        type: integer
        format: uint32
      value:
        x-go-type:
          type: "json.RawMessage"
          hints:
            noValidation: true
      del:
        type: boolean

  Metadata:
    type: object
    description: user's TileDB metadata
    properties:
      entries:
        description: List of metadata entries
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/MetadataEntry"

  GroupCreationRequest:
    type: object
    description: information for creating a new group with the passed configuration
    required:
      - group_details
    properties:
      config:
        $ref: "#/definitions/TileDBConfig"
      group_details:
        description: Initial attributes for the creation of a group.
        type: object
        properties:
          description:
            description: A human readable description of the contents of the group.
            type: string
          name:
            description: The name of the group. If must be unique within the group.
            type: string
          uri:
            description: uri of group.
            type: string
            x-omitempty: false
          logo:
            description: logo (base64 encoded) for the group. Optional
            type: string
          tags:
            description: optional tags for groups.
            x-omitempty: false
            type: array
            items:
              type: string
              description: tag must be lowercase characters or hypen [a-z-].
          license_id:
            type: string
            x-omitempty: true
            description: License identifier from SPDX License List or Custom.
          license_text:
            type: string
            x-omitempty: true
            description: License text

  GroupCreationResponse:
    description: Information of the created group
    type: object
    properties:
      id:
        type: string
        description: The UUID of the created Group
        x-omitempty: false
      name:
        type: string
        description: The name of the created Group
        x-omitempty: false
      tiledb_uri:
        type: string
        description: TileDB URI for access
        x-omitempty: false

  GroupRegistrationRequest:
    type: object
    description: information for creating a new group with the passed configuration
    required:
      - group_details
    properties:
      config:
        $ref: "#/definitions/TileDBConfig"
      group_details:
        description: Initial attributes for the creation of a group.
        type: object
        properties:
          description:
            description: A human readable description of the contents of the group.
            type: string
          name:
            description: The name of the group. If must be unique within the group.
            type: string
          parent:
            description: The unique name or id of the parent of the group. If empty, then the new group will be a top level group.
            type: string
          uri:
            description: uri of group.
            type: string
            x-omitempty: false
          logo:
            description: logo (base64 encoded) for the group. Optional
            type: string
          tags:
            description: optional tags for groups.
            x-omitempty: false
            type: array
            items:
              type: string
              description: tag must be lowercase characters or hypen [a-z-].
          license_id:
            type: string
            x-omitempty: true
            description: License identifier from SPDX License List or Custom.
          license_text:
            type: string
            x-omitempty: true
            description: License text
          region:
            type: string
            x-omitempty: true
            description: region of the group
          access_credentials_name:
            description: the name of the access credentials to use. if unset, the default credentials will be used.
            type: string

  GroupContentsRetrievalResponse:
    description: Object including a page of members of a group and pagination metadata
    type: object
    properties:
      members:
        description: Groups members
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/GroupMember"
      metadata:
        description: Group metadata
        x-omitempty: true
        $ref: "#/definitions/Metadata"

  GroupContentsRetrievalRequest:
    description: Request the contents of a group
    type: object
    properties:
      config:
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"

  GroupContentsChangesRequest:
    description: Updates the contents group
    type: object
    properties:
      config:
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"
      group_changes:
        type: object
        properties:
          members_to_remove:
            description: optional series of members to remove
            x-omitempty: false
            type: array
            items:
              type: string
              description: uris of members to remove
          members_to_add:
            description: optional series of members to add
            x-omitempty: false
            type: array
            items:
              description: group members to add
              $ref: "#/definitions/GroupMember"

  GroupMetadataUpdateRequest:
    description: Updates the metadata of a group
    type: object
    required:
      - metadata
    properties:
      config:
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"
      metadata:
        $ref: "#/definitions/Metadata"

  GroupMetadataRetrievalRequest:
    description: Retrieves the metadata of a group
    type: object
    properties:
      config:
        type: object
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"

  GroupMemberType:
    description: File types that can be included in groups
    type: string
    enum:
      # Group
      - GROUP
      # Array
      - ARRAY

  GroupMemberAssetType:
    description: Specific file types of group members
    type: string
    enum:
      # Group
      - group
      # Array
      - array
      # Notebook
      - notebook
      # Dashboard
      - dashboard
      # UDF
      - user_defined_function
      # ML Model
      - ml_model
      # Files
      - file
      # Biomedical Imaging
      - bioimg
      # SOMA
      - soma
      # VCF
      - vcf
      # Point Cloud
      - pointcloud
      # Raster
      - raster
      # Geometry
      - geometry
      # Vector search
      - vector_search

  GroupMember:
    description: A groups member, array or another groups, to add or remove from an existing group.
    type: object
    properties:
      name:
        description: The name of the member
        type: string
      uri:
        description: The uri of the member
        type: string
      type:
        $ref: "#/definitions/GroupMemberType"

  GroupContentActivity:
    description: Object containing activity of an asset of a group
    type: object
    properties:
      asset:
        description: The asset details
        type: object
        properties:
          id:
            description: The asset ID
            type: string
          name:
            description: The asset name
            type: string
          namespace:
            description: The namespace that the asset belongs to
            type: string
          asset_type:
            description: The type of the asset
            $ref: "#/definitions/AssetType"
      activity_log:
        description: Object containing the activity log
        type: object
        $ref: "#/definitions/ArrayActivityLog"

  GroupContentActivityResponse:
    description: Object containing activity logs of group content along with the pagination metadata
    type: object
    properties:
      activity:
        description: Activity of a group's content
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/GroupContentActivity"
      pagination_metadata:
        x-omitempty: false
        $ref: "#/definitions/PaginationMetadata"

  GroupActivityResponse:
    description: Object containing activity logs of a group and its content (arrays and subgroups) along with pagination metadata
    type: object
    properties:
      activity_logs:
        description: Array of activity logs, including both group and array activities
        type: array
        x-omitempty: false
        items:
          $ref: '#/definitions/AssetActivityLog'
      pagination_metadata:
        x-omitempty: false
        $ref: "#/definitions/PaginationMetadata"

  GroupActivityEventType:
    description: Event type of Group activity
    type: string
    enum:
      # create operation
      - create
      # update operation
      - update
      # delete operation
      - delete
      # register operation
      - register
      # deregister operation
      - deregister
      # add member operation
      - group_member_add
      # get member operation
      - group_member_get
      # remove member operation
      - group_member_remove
      # get metadata operation
      - group_metadata_get
      # update metadata operation
      - group_metadata_update
      # delete metadata operation
      - group_metadata_delete
      # serialize metadata operation
      - group_metadata_serialize
      # deserialize metadata operation
      - group_metadata_deserialize
      # consolidate metadata operation
      - group_metadata_consolidate
      # vacuum metadata operation
      - group_metadata_vacuum
      # set configuration operation
      - config_set
      # get configuration operation
      - config_get

  TileDBConfig:
    description: TileDB config used for interaction with the embedded library
    type: object
    properties:
      entries:
        type: array
        items:
          type: object
          properties:
            key:
              type: string
            value:
              type: string

  FileUploaded:
    description: Uploaded file name and information
    type: object
    required:
      - id
    properties:
      output_uri:
        type: string
        description: output location of the TileDB File
      file_name:
        type: string
        description: name of the file uploaded
      id:
        description: unique ID of the uploaded file
        type: string
        example: "00000000-0000-0000-0000-000000000000"
        x-omitempty: false

  NotebookUploaded:
    description: Uploaded notebook name and information
    type: object
    required:
      - id
    properties:
      output_uri:
        type: string
        description: output location of the TileDB Notebook
      name:
        type: string
        description: name of the notebook uploaded
      id:
        description: unique ID of the uploaded notebook
        type: string
        example: "00000000-0000-0000-0000-000000000000"
        x-omitempty: false

  ArrayFetch:
    description: Model for opening an array v2
    type: object
    properties:
      config:
        $ref: "#/definitions/TileDBConfig"
      queryType:
        description: Array opened for query type
        $ref: "#/definitions/Querytype"

paths:
  /arrays/{namespace}/{array}:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
      - name: Content-Type
        in: header
        description: Content Type of input and return mime
        type: string
        required: true
        default: application/json
    post:
      description: Get a array at a specified URI registered to a group/project
      tags:
        - array
      operationId: getArray
      parameters:
        - name: ArrayFetch
          in: body
          description: Details for array being fetched
          schema:
            $ref: "#/definitions/ArrayFetch"
          required: true
      responses:
        200:
          description: Array opened successfully
          schema:
            $ref: "#/definitions/Array"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/query/submit:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
      - name: type
        in: query
        description: type of query
        required: true
        type: string
      - name: Content-Type
        in: header
        description: Content Type of input and return mime
        type: string
        required: true
        default: application/json
      - name: X-Payer
        in: header
        description: Name of organization or user who should be charged for this request
        type: string
      - name: open_at
        description: open_at for array in unix epoch
        in: query
        type: integer
        format: uint64
      - name: read_all
        in: query
        description: If "true", resubmits incomplete queries until the query has completed. Defaults to "false".
        type: string
    post:
      description: send a query to run against a specified array/URI registered to a group/project
      tags:
        - query
      produces:
        - application/json
        - application/capnp
      consumes:
        - application/json
        - application/capnp
      operationId: submitQuery
      parameters:
        - name: query
          in: body
          description: query to run
          schema:
            $ref: "#/definitions/Query"
          required: true
      responses:
        200:
          description: query completed and results are returned in query object
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed query
          schema:
            type: file
            format: byte
            description: The first 8-bytes contains a little-endian ordered unsigned integer that contains the total byte size of the following Query object. If 'read_all' was set, this will repeat with 0-padding until reaching a Query object with a non-incomplete status.
        204:
          description: query completed successfully with no return
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/activity:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
      - name: start
        in: query
        description: "Start time of window of fetch logs, unix epoch in seconds (default: seven days ago)"
        type: integer
        format: uint64
        required: false
      - name: end
        in: query
        description: "End time of window of fetch logs, unix epoch in seconds (default: current utc timestamp)"
        type: integer
        format: uint64
        required: false
      - name: event_types
        in: query
        collectionFormat: multi
        type: array
        items:
          type: string
        description: Refer to ActivityEventType for possible values
      - name: task_id
        in: query
        type: string
        description: Array task id To filter activity to
      - name: has_task_id
        in: query
        type: boolean
        description: Excludes activity log results that does not contain an array task uuid
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: get array activity logs
      tags:
        - array
      operationId: arrayActivityLog
      responses:
        200:
          description: log of array activity
          schema:
            $ref: "#/definitions/ArrayActivityLogData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /credentials/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace
        required: true
        type: string
      - name: provider
        in: query
        description: "Show only the credentials from this provider. This should be one of the CloudProvider enum values."
        type: string
      - name: type
        in: query
        description: "Show only the credentials of this type. This should be one of the AccessCredentialType enum values."
        type: string
      - name: page
        in: query
        description: pagination offset
        type: integer
      - name: per_page
        in: query
        description: pagination limit
        type: integer
    get:
      tags:
        - user
        - organization
      description: "List the credentials available in the namespace"
      operationId: listCredentials
      responses:
        200:
          description: "Available credentials are returned"
          schema:
            $ref: "#/definitions/AccessCredentialsData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - user
        - organization
      description: "Create a new credential for the namespace"
      operationId: addCredential
      parameters:
        - name: accessCredential
          in: body
          description: "The new credentials to be created."
          schema:
            $ref: "#/definitions/AccessCredential"
          required: true
      responses:
        204:
          description: "The new credential was successfully added."
        502:
          description: Bad Gateway
        default:
          description: "error response"
          schema:
            $ref: "#/definitions/Error"

  /credentials/{namespace}/{name}:
    parameters:
      - name: namespace
        in: path
        description: namespace
        required: true
        type: string
      - name: name
        in: path
        description: "A URL-safe version of the credential's user-provided name"
        required: true
        type: string
    get:
      tags:
        - user
        - organization
      description: "Retrieve an access credential by name"
      operationId: getCredential
      responses:
        200:
          description: "Credential exists and can be returned"
          schema:
            $ref: "#/definitions/AccessCredential"
        502:
          description: Bad Gateway
        default:
          description: "error response"
          schema:
            $ref: "#/definitions/Error"
    patch:
      tags:
        - user
        - organization
      description: "Update the named access credential. This will also update the information used to access arrays set to use this credential."
      operationId: updateCredential
      parameters:
        - name: accessCredential
          in: body
          description: "Changes to make to this credential"
          schema:
            $ref: "#/definitions/AccessCredential"
          required: true
      responses:
        204:
          description: "The credential was updated successfully"
        502:
          description: Bad Gateway
        default:
          description: "Error response"
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - user
        - organization
      description: "Delete the named access credential. Any arrays still set to use this credential will use the namespace's default and may become unreachable."
      operationId: deleteCredential
      responses:
        204:
          description: "The credential was deleted successfully"
        502:
          description: Bad Gateway
        default:
          description: "Error response"
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/metadata:
    parameters:
      - name: group_namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: group_name
        type: string
        in: path
        required: true
        description: The unique name or id of the group
    post:
      operationId: getGroupMetadata
      description: get metadata on a group using the requested config
      tags:
        - groups
      parameters:
        - name: metadataRetrieval
          in: body
          schema:
            $ref: "#/definitions/GroupMetadataRetrievalRequest"
      responses:
        200:
          description: retrieve metadata for a group
          schema:
            $ref: "#/definitions/Metadata"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    put:
      operationId: updateGroupMetadata
      description: update metadata on a group
      tags:
        - groups
      parameters:
        - name: metadataUpdating
          in: body
          schema:
            $ref: "#/definitions/GroupMetadataUpdateRequest"
      responses:
        200:
          description: group metadata updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}:
    parameters:
      - name: group_namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
    post:
      description: Creates an empty group
      operationId: createGroup
      tags:
        - groups
      parameters:
        - name: groupCreation
          in: body
          schema:
            $ref: "#/definitions/GroupCreationRequest"
      responses:
        201:
          description: group created successfully
          schema:
            $ref: "#/definitions/GroupCreationResponse"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    put:
      description: Registers an already existing group
      operationId: registerGroup
      tags:
        - groups
      parameters:
        - name: groupRegistration
          in: body
          schema:
            $ref: "#/definitions/GroupRegistrationRequest"
      responses:
        201:
          description: group created successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}:
    parameters:
      - name: group_namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: group_name
        type: string
        in: path
        required: true
        description: The unique name or id of the group
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
    options:
      description: can be used to check if the resource exists
      tags:
        - groups
      responses:
        404:
          description: the resource does not exist
        204:
          description: the resource exists
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: Retrieves the contents of a group
      operationId: retrieveGroup
      tags:
        - groups
      parameters:
        - name: groupRetrieval
          in: body
          schema:
            $ref: "#/definitions/GroupContentsRetrievalRequest"
      responses:
        200:
          description: group created successfully
          schema:
            $ref: "#/definitions/GroupContentsRetrievalResponse"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Change the contents of the group
      operationId: updateGroupContents
      tags:
        - groups
      parameters:
        - name: groupUpdateContents
          in: body
          schema:
            $ref: "#/definitions/GroupContentsChangesRequest"
      responses:
        204:
          description: attributes changed successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      parameters:
        - name: recursive
          in: query
          description: If true, it descends in the group and deregisters every subgroup and subarray
          type: string
          required: false
      description: Deregisters a group
      operationId: deregisterGroup
      tags:
        - groups
      responses:
        200:
          description: group deregistered successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/delete:
    parameters:
      - name: group_namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: group_name
        type: string
        in: path
        required: true
        description: The unique name or id of the group
      - name: recursive
        in: query
        description: If true, it descends in the group and deletes every subgroup and subarray
        type: string
        required: false
    delete:
      description: Deregisters and physically deletes a group
      operationId: deleteGroup
      tags:
        - groups
      responses:
        204:
          description: group deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/content_activity:
    parameters:
      - name: group_namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: group_name
        type: string
        in: path
        required: true
        description: The unique name or id of the group
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: Retrieves combined activity logs for all assets contained in a group.
      operationId: getGroupContentActivity
      tags:
        - groups
      responses:
        200:
          description: Activity logs of group contents along with the pagination metadata
          schema:
            $ref: "#/definitions/GroupContentActivityResponse"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/activity:
    parameters:
      - name: group_namespace
        in: path
        description: namespace group is in (an organization name or user's username)
        type: string
        required: true
      - name: group_name
        in: path
        description: name/uri of group that is url-encoded
        type: string
        required: true
      - name: start
        in: query
        description: "Start time of window of fetch logs, unix epoch in seconds (default: seven days ago)"
        type: integer
        format: uint64
        required: false
      - name: end
        in: query
        description: "End time of window of fetch logs, unix epoch in seconds (default: current utc timestamp)"
        type: integer
        format: uint64
        required: false
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: Retrieves activity logs for all assets contained in a group (arrays and other groups) including the parent group itself.
      operationId: getGroupActivity
      tags:
        - groups
      responses:
        '200':
          description: Activity logs of group and all its content along with the pagination metadata
          schema:
            $ref: "#/definitions/GroupActivityResponse"
        '502':
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /files/{namespace}/{array}/upload:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the file
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
      - name: Content-Type
        in: header
        description: Content Type of input
        type: string
        required: true
        default: application/octet-stream
      - name: name
        in: query
        description: name of the TileDB array to create, if missing {array} is used
        type: string
        required: false
      - name: filename
        in: query
        description: original file name
        type: string
        required: false
      - name: filesize
        in: query
        description: size of the file to upload in bytes
        type: integer
        format: uint64
        required: true
      - name: mimetype
        in: query
        description: |
          Mime type of the uploaded file. Autogenerated clients do
          not always support changing the content type param. Server will
          always use mimetype query param to set mimetype for file,
          if it is not set Content-Type will be used
        type: string
        required: false
    post:
      description: Upload a file at the specified location and wrap it in TileDB Array
      consumes:
        - application/octet-stream
      produces:
        - application/json
      tags:
        - files
      operationId: HandleUploadFile
      parameters:
        - name: file
          in: body
          description: file to upload
          schema:
            type: string
            format: binary
            description: File contents
          required: true
      responses:
        201:
          description: File uploaded
          schema:
            $ref: "#/definitions/FileUploaded"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/{array}/upload:
    parameters:
      - name: namespace
        type: string
        in: path
        required: true
        description: The namespace of the notebook
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
      - name: name
        in: query
        description: name of the TileDB array to create, if missing {array} is used
        type: string
        required: false
      - name: filesize
        in: query
        description: size of the notebook to upload in bytes
        type: integer
        format: uint64
        required: true
    post:
      description: Upload a notebook at the specified location and wrap it in TileDB Array
      consumes:
        - application/octet-stream
      produces:
        - application/json
      tags:
        - notebooks
      operationId: HandleUploadNotebook
      parameters:
        - name: notebook
          in: body
          description: notebook to upload
          schema:
            type: string
            format: binary
            description: Notebook contents
          required: true
      responses:
        201:
          description: Notebook uploaded
          schema:
            $ref: "#/definitions/NotebookUploaded"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"