openapi-v1.yaml

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

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

schemes:
  - http
  - https

basePath: /v1

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:
  ArrayType:
    description: TileDB array type
    type: string
    enum:
      # Dense array
      - dense
      # Sparse array
      - sparse

  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

  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
      # query delete operation
      - query_delete
      # 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
      # read_fragment_info
      - read_fragment_info

  UDFLanguage:
    description: UDF Type
    type: string
    enum:
      # python
      - python
      # r
      - r

  UDFType:
    description: UDF Type
    type: string
    enum:
      # multi_array
      - multi_array
      # single_array
      - single_array
      # generic
      - generic

  ResultFormat:
    description: "Data format of a result"
    type: string
    enum:
      - python_pickle
      - r_serialization
      - json
      - arrow
      - bytes
        # Raw binary data, not interpreted by the loader.
      - tiledb_json
        # The format used to encode argument values for a task graph: JSON
        # as deeply as possible, but any value that cannot be JSON-encoded
        # is replaced with a TGArgValue.
      - native # DEPRECATED. Use the language-specific values instead.

  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
      # Delete
      - DELETE

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

  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

  FilterOption:
    description: TileDB filter option
    type: string
    enum:
      # Compression level. Type: `int32_t`
      - COMPRESSION_LEVEL
      # Max window length for bit width reduction. Type: `uint32_t`
      - BIT_WIDTH_MAX_WINDOW
      # Max window length for positive-delta encoding. Type: `uint32_t`.
      - POSITIVE_DELTA_MAX_WINDOW

  OrganizationRoles:
    description: role user has in organization
    type: string
    enum:
      # Owner/creator of group
      - owner
      # Admin almost all rights but can't delete organization
      - admin
      # Read and write User
      - read_write
      # Read Only User
      - read_only

  ArrayActions:
    description: actions a user can take on an array
    type: string
    enum:
      # Read
      - read
      # Write
      - write
      # Edit metadata about array
      - edit
      # View logs for array
      - read_array_logs
      # Permission to get array info
      - read_array_info
      # Permission to fetch the array schema
      - read_array_schema

  UDFActions:
    description: actions a user can take on a UDF
    type: string
    enum:
      # Fetch UDF and run jobs
      - fetch_udf
      # Share UDF with others
      - share_udf

  NamespaceActions:
    description: actions a user can take on an organization
    type: string
    enum:
      # Fetch details about namespace and read arrays in namespace
      - read
      # Write to arrays inside namespace
      - write
      # Create arrays inside namespace
      - create
      # Delete/Deregister arrays in namespace
      - delete
      # Edit array metadata
      - edit
      # View logs for array
      - read_array_logs
      # View logs for job
      - read_job_logs
      # View change logs for namespace
      - read_object_logs
      # Run job
      - run_job
      # Delete an organization
      - delete_organization
      # Edit organization details
      - edit_organization
      # Edit billing details
      - edit_billing

  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:
      - timestamp
      - queryType
      - uri
    properties:
      timestamp:
        description: timestamp (epoch milliseconds) array is opened at
        type: number
        format: uint64
        example: 1540471791873
      queryType:
        description: Array opened for query type
        $ref: "#/definitions/Querytype"
      uri:
        description: Array uri
        type: string

  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
      fillValue:
        description: The default fill value
        type: array
        items:
          type: integer
          format: uint8

  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"

  Filter:
    description: Filter
    type: object
    required:
      - type
    properties:
      type:
        description: Filter type
        $ref: "#/definitions/FilterType"
      data:
        description: Filter data
        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:
    description: One or more filters to apply
    type: object
    properties:
      filters:
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Filter"

  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"
      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"
      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
    x-go-type:
      import:
        package: "github.com/TileDB-Inc/TileDB-Go"
        alias: "tiledb"
      type: "ArraySchema"

  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

  Writer:
    type: object
    properties:
      checkCoordDups:
        type: boolean
      checkCoordOOB:
        type: boolean
      dedupCoords:
        type: boolean
      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

  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"
      varOffsetsMode:
        description: The offsets format (bytes or elements) to be used.
        type: string
      varOffsetsAddExtraElement:
        description: True if an extra element will be added to the end of the offsets buffer.
        type: boolean
      varOffsetsBitsize:
        description: The offsets bitsize (32 or 64) to be used.
        type: integer
        format: uint32

  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
    x-go-type:
      import:
        package: "github.com/TileDB-Inc/TileDB-Go"
        alias: "tiledb"
      type: "Query"

  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

  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

  MaxBufferSizes:
    type: object
    description: a list of max buffer sizes, one per attribute
    properties:
      maxBufferSizes:
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/AttributeBufferSize"

  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"

  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


  ArrayActivityLog:
    description: Actvity 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, "...": "..."}}'

  ArrayTaskType:
    description: Synchronous Task Type
    type: string
    enum:
      - SQL
      - UDF
      - QUERY
      - GENERIC_UDF
      - BATCH_UDF
      - CLIENT_COMPUTATION

  ArrayTaskStatus:
    description: Status of array task
    type: string
    enum:
      - QUEUED
      - FAILED
      - COMPLETED
      - RUNNING
      - RESOURCES_UNAVAILABLE
      - UNKNOWN
      - CANCELLED
      - DENIED # Deprecated; used to mean RESOURCES_UNAVAILABLE.

  ArrayTaskLog:
    description: Array task stderr/stdout logs
    type: object
    properties:
      array_task_id:
        description: ID of associated task
        type: string
      logs:
        description: logs from array task
        type: string

  ArrayTask:
    description: Synchronous Task to Run
    type: object
    properties:
      id:
        description: task ID
        type: string
      name:
        description: Optional task name
        type: string
        example: "subarray-multiplier"
      username:
        description: username that executed this task
        type: string
        example: "demo"
      description:
        description: Optional task description (Tasks purpose)
        type: string
        example: "Return attr a1 in the subarray bounded by coordinates and multiply attr1 by 2"
      array_metadata:
        description: Metadata of the array used in the context of this task
        $ref: "#/definitions/ArrayInfo"
      subarray:
        description: A subarray to run the array task on
        $ref: "#/definitions/DomainArray"
        example:
          - Dim1:
              Int64: 0
                10
            Dim2:
              Int64: 20
                22
            Dim3:
              Int64: 10000
                10100
      memory:
        description: memory allocated to task in bytes
        type: integer
        format: uint64
        example: 1073741824
      cpu:
        description: millicpu allocated to task
        type: integer
        format: uint64
        example: 4000
      namespace:
        type: string
        description: namespace task is tied to
        example: "organization1"
      status:
        description: The status of an individual task
        $ref: "#/definitions/ArrayTaskStatus"
      status_message:
        description: The reason the array task status is in the state
        type: string
        x-nullable: true
        x-omitempty: true
      start_time:
        description: Start time RFC3339 for job
        type: string
        format: date-time
      finish_time:
        description: Finish time RFC3339 for job
        type: string
        format: date-time
        x-nullable: true
      cost:
        description: Total accumulated for task in USD, example is $0.12
        type: number
        format: double
        example: 0.12
      egress_cost:
        description: Total accumulated for egress task in USD, example is $0.12
        type: number
        format: double
        example: 0.12
      access_cost:
        description: Cost accumulated for access task in USD, example is $0.12
        type: number
        format: double
        example: 0.12
      query_type:
        description: If task type is query, whether it's a read or write query
        $ref: "#/definitions/Querytype"
      udf_code:
        description: Optional actual code that is going to be executed
        type: string
      udf_language:
        description: Optional actual language used to express udf_code
        type: string
      sql_query:
        description: Optional actual sql query that is going to be executed
        type: string
      type:
        description: Type of task
        $ref: "#/definitions/ArrayTaskType"
      activity:
        description: Array activity logs for task
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActivityLog"
      logs:
        description: logs from array task
        type: string
        x-omitempty: false
      duration:
        description: duration in nanoseconds of an array task
        type: number
        example: 341000000000
      sql_init_commands:
        description: SQL queries or commands to run before main sql query
        type: array
        items:
          type: string
          description: sql query or command to run before main sql query
      sql_parameters:
        description: SQL query parameters
        type: array
        items: {}
      result_format:
        $ref: "#/definitions/ResultFormat"
        description: type of results (native, i.e cloud pickle or json or arrow)
        x-omitempty: true
      task_graph_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the ID of the log for the task graph that this was part of.
      client_node_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the client-defined ID of the node within this task's graph.

  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

  ArrayTaskData:
    description: Object including array tasks and metadata
    type: object
    properties:
      array_tasks:
        description: Array Tasks
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayTask"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  ArrayTaskBrowserSidebar:
    description: Object for ui array tasks browser page
    type: object
    properties:
      organizations:
        description: list of all unique organizations the user is part of that have array tasks
        type: array
        x-omitempty: false
        items:
          type: string
      result_count_for_all:
        description: A count of "all"
        x-omitempty: false
        type: integer
      result_count_by_namespace:
        description: A map that includes the result count by namespace
        x-omitempty: false
        additionalProperties:
          type: integer

  LastAccessedArray:
    type: object
    description: Information related to last access of an array
    properties:
      array_id:
        type: string
        description: unique ID of array
        example: "00000000-0000-0000-0000-000000000000"
      array_name:
        type: string
        description: name of the array
        example: array1
      namespace:
        description: namespace of a user or organization
        type: string
        example: "mockuser"
      accessed_time:
        description: timestamp (epoch milliseconds) array is last accessed
        type: number
        format: uint64
        example: 1540471791873
      access_type:
        description: Type of the event
        $ref: "#/definitions/ActivityEventType"

  ArraySample:
    type: object
    description: Sample data from array
    properties:
      data:
        additionalProperties:
          type: object

  ArrayMetadataJson:
    type: object
    description: Metadata from array in Json format
    additionalProperties: true

  NonEmptyDomainJson:
    type: object
    description: Non-empty domain from array in Json format
    additionalProperties: true

  ArrayBrowserData:
    description: Object including array info and pagination metadata
    type: object
    properties:
      arrays:
        description: Array Info
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  ArrayEndTimestampData:
    description: Object including array end_timestamps (list of Unix epoch timestamps in milliseconds) and pagination metadata
    type: object
    properties:
      end_timestamps:
        description: List of timestamps expressed in milliseconds since Unix epoch
        type: array
        x-omitempty: true
        items:
          type: integer
          format: uint64
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  ArrayBrowserSidebar:
    description: Object for ui array tasks browser page
    type: object
    properties:
      namespaces:
        description: list of all unique namespaces to display
        type: array
        x-omitempty: false
        items:
          type: string
      result_count_for_all:
        description: A count of "all" of category
        x-omitempty: false
        type: integer
      result_count_by_namespace:
        description: A map that includes the result count by namespace
        x-omitempty: false
        additionalProperties:
          type: integer

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

  User:
    description: User
    type: object
    required:
      - username
    properties:
      id:
        type: string
        description: unique ID of user
        example: "00000000-0000-0000-0000-000000000000"
      username:
        type: string
        minLength: 1
        maxLength: 63
        pattern: "^[\\w.\\-]+$" # only allows alphanumeric characters
        description: username must be unique
        example: "username"
      password:
        type: string
        minLength: 8
        description: password
        example: "password"
      name:
        description: the user's full, real name
        type: string
        minLength: 1
        example: "Jane Doe"
      email:
        description: the user's email
        type: string
        example: "jane.doe@example.com"
      is_valid_email:
        description: user's email is validated to be correct
        type: boolean
        readOnly: true
        example: false
      stripe_connect:
        description: Denotes that the user is able to apply pricing to arrays by means of Stripe Connect
        type: boolean
        readOnly: true
        example: false
      company:
        description: the user's company
        type: string
        example: TileDB
      logo:
        description: the user's logo
        type: string
        x-nullable: true
      timezone:
        type: string
        example: Europe/Athens
      organizations:
        type: array
        x-omitempty: true
        description: Array of organizations a user is part of and their roles
        readOnly: true
        items:
          $ref: "#/definitions/OrganizationUser"
      allowed_actions:
        description: list of actions user is allowed to do on this organization
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/NamespaceActions"
      enabled_features:
        description: List of extra/optional/beta features to enable for namespace
        type: array
        x-omitempty: true
        readOnly: true
        items:
          type: string
      unpaid_subscription:
        description: A notice that the user has an unpaid subscription
        type: boolean
        readOnly: true
        x-omitempty: false
      default_s3_path:
        description: >
          The default location to store newly-created notebooks and other assets
          like UDFs. The name `default_s3_path` is a legacy holdover; it may
          refer to any supported storage location.
        type: string
      default_s3_path_credentials_name:
        description: >
          The name of the credentials used to create and access files in the
          `default_s3_path`, if needed.
      asset_locations:
        $ref: "#/definitions/AssetLocations"
      default_namespace_charged:
        description: Override the default namespace charged for actions when no namespace is specified
        type: string

  OrganizationUser:
    description: user in an organization
    type: object
    properties:
      user_id:
        type: string
        description: unique ID of user
        example: "00000000-0000-0000-0000-000000000000"
      organization_id:
        type: string
        description: unique ID of organization
        example: "00000000-0000-0000-0000-000000000000"
      username:
        description: username for user
        type: string
        example: "username"
      organization_name:
        description: name of organization
        type: string
        example: "MyOrganization"
      role:
        $ref: "#/definitions/OrganizationRoles"
      allowed_actions:
        description: list of actions user is allowed to do on this organization
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/NamespaceActions"

  DomainVerificationStatus:
    description: The current status of the claim on the domain.
    type: string
    enum:
      - unverified
        # A newly-registered claim which has not been verified.
      - verified
        # The claim has been verified and the ownership claim is active.
      - grace_period
        # Verification is failing, but to ensure continuity of service,
        # we allow a period of failure before deactivating the claim.
      - failed
        # The domain verification was not found and the ownership claim
        # is inactive.

  DomainCheckStatus:
    description: The status of a single check on a domain's status.
    type: string
    enum:
      - verified
        # Verification was successful and the claim was found.
      - failed
        # Verification completed without error and the claim was not found.
      - error
        # An internal error occurred when performing verification.

  DomainCheckResult:
    description: The record of a check of a single domain's status.
    type: object
    properties:
      time:
        type: string
        format: date-time
        description: The timestamp when the check was performed.
      status:
        $ref: '#/definitions/DomainCheckStatus'

  SSODomainConfig:
    description: >
      The information used to set up a single-sign on connection to a customer
      domain.
    type: object
    properties:
      uuid:
        type: string
        description: A server-generated ID for the configuration.
      domain:
        type: string
        description: >
          The fully-qualified domain (but with no trailing dot) to connect for
          single sign-on. This may not be changed after creation.
        x-nullable: true
      oidc_issuer:
        type: string
        description: >
          The URL of the OpenID Connect issuer that can be used to authenticate
          this domain's users. The prefix where the
          `/.well-known/openid-configuration` file can be found; usually without
          a trailing slash.
      oidc_client_id:
        type: string
        description: The OpenID Connect client ID for this SSO instance.
      oidc_client_secret:
        type: string
        description: The OpenID Connect client secret for this SSO instance.
        x-go-custom-tag: 'tdbrest:"secret"'
      domain_setup:
        $ref: '#/definitions/SSODomainSetup'
      verification_status:
        $ref: '#/definitions/DomainVerificationStatus'
      check_results:
        description: >
          A list of the results of recent attempts to verify this domain.
        type: array
        items:
          $ref: '#/definitions/DomainCheckResult'

  SSODomainConfigResponse:
    description: >
      The response to a request for the list of domain claims associated with
      a particular organization.
    type: object
    properties:
      domain_configs:
        type: array
        items:
          $ref: '#/definitions/SSODomainConfig'

  SSODomainSetup:
    description: >
      Configuration settings to verify ownership of a given domain. At least one
      of these must be completed enable user login from the domain.
    type: object
    properties:
      txt:
        description: a DNS TXT record to set on the domain to claim.
        type: string
      cname_src:
        description: a DNS name to set a CNAME record on
        type: string
      cname_dst:
        description: the CNAME target of `cname_src`.
        type: string

  Organization:
    description: Organization
    type: object
    required:
      - name
    properties:
      id:
        type: string
        description: unique ID of organization
        example: "00000000-0000-0000-0000-000000000000"
      role:
        description: role of requested user within this organization
        $ref: "#/definitions/OrganizationRoles"
      name:
        type: string
        minLength: 1
        maxLength: 63
        pattern: "^[\\w.\\-]+$" # only allows alphanumeric characters
        description: organization name must be unique
      created_at:
        description: Datetime organization was created in UTC
        type: string
        format: date-time
      updated_at:
        description: Datetime organization was updated in UTC
        type: string
        format: date-time
      logo:
        description: Organization logo
        type: string
        x-nullable: true
      description:
        description: Organization description
        type: string
        x-nullable: true
      users:
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/OrganizationUser"
      allowed_actions:
        description: list of actions user is allowed to do on this organization
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/NamespaceActions"
      num_of_arrays:
        description: number of registered arrays for this organization
        type: number
        format: int32
        x-omitempty: false
      enabled_features:
        description: List of extra/optional/beta features to enable for namespace
        type: array
        x-omitempty: true
        readOnly: true
        items:
          type: string
      unpaid_subscription:
        description: A notice that the user has an unpaid subscription
        type: boolean
        readOnly: true
        x-omitempty: false
      default_s3_path:
        description: >
          The default location to store newly-created notebooks and other assets
          like UDFs. The name `default_s3_path` is a legacy holdover; it may
          refer to any supported storage location.
        type: string
      default_s3_path_credentials_name:
        description: >
          The name of the credentials used to create and access files in the
          `default_s3_path`, if needed.
        type: string
      asset_locations:
        $ref: "#/definitions/AssetLocations"
      stripe_connect:
        description: Denotes that the organization is able to apply pricing to arrays by means of Stripe Connect
        type: boolean
        readOnly: true
        example: false

  AssetLocations:
    description: >
      Custom storage locations on a per–asset type basis. If any is unset,
      a suffix of the owning (user/organization) `default_s3_path` is used.
    type: object
    properties:
      arrays:
        $ref: '#/definitions/StorageLocation'
      files:
        $ref: '#/definitions/StorageLocation'
      groups:
        $ref: '#/definitions/StorageLocation'
      ml_models:
        $ref: '#/definitions/StorageLocation'
      notebooks:
        $ref: '#/definitions/StorageLocation'
      task_graphs:
        $ref: '#/definitions/StorageLocation'
      udfs:
        $ref: '#/definitions/StorageLocation'

  StorageLocation:
    description: >
      The path at which a given asset will be stored, and the credentials used
      to access that asset.
    type: object
    properties:
      path:
        description: >
          The path to store this asset type. If unset, a suffix of the user's
          `default_s3_path` is used. When updating, explicitly set to `""`,
          the empty string, to clear this path; leaving it `null` (or absent)
          will leave the path unchanged.
        x-nullable: true
        type: string
      credentials_name:
        description: >
          The name of the credentials used to acess this storage path. If unset,
          the `default_s3_path_credentials_name` is used. When updating,
          explicitly set to `""`, the empty string, to clear this name;
          leaving it `null` (or absent) will leave the name unchanged.
        x-nullable: true
        type: string

  ArraySharing:
    description: details for sharing a given array
    type: object
    properties:
      actions:
        description: List of permitted actions
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActions"
        example:
          - read
          - write
      namespace:
        description: namespace being granted array access can be a user or organization
        type: string
        example: "MyOrganization"
      namespace_type:
        description: details on if the namespace is a organization or user
        type: string
        example: "organization"

  UDFSharing:
    description: details for sharing a given UDF
    type: object
    properties:
      actions:
        description: List of permitted actions
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/UDFActions"
        example:
          - fetch
          - share
      namespace:
        description: namespace being granted array access can be a user or organization
        type: string
        example: "MyOrganization"
      namespace_type:
        description: details on if the namespace is a organization or user
        type: string
        example: "organization"

  FileType:
    description: File types represented as TileDB arrays
    type: string
    enum:
      # Notebook
      - notebook
      # UDF
      - user_defined_function
      # ML Model
      - ml_model
      # Files
      - file
      # Task graphs
      - registered_task_graph

  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      

  FilePropertyName:
    description: File property assigned to a specific file (array)
    type: string
    enum:
      # Image name
      - image
      # Size
      - size
      # Code block
      - code_block
      # UDF language
      - udf_language
      # Is dashboard
      - is_dashboard
      # version_pruning_limit
      - version_pruning_limit
      # version_pruning_enabled
      - version_pruning_enabled

  PricingType:
    description: Pricing types
    type: string
    enum:
      # Egress pricing
      - egress
      # Access pricing
      - access

  PricingCurrency:
    description: Currency of pricing
    type: string
    enum:
      # US Dollars
      - USD

  PricingUnitLabel:
    description: Unit label
    type: string
    enum:
      # Byte
      - byte
      # Second
      - second

  PricingAggregateUsage:
    description: Specifies a usage aggregation strategy for pricings of usage_type=metered
    type: string
    enum:
      # For summing up all usage during a period
      - sum

  PricingInterval:
    description: Interval for pricing
    type: string
    enum:
      # Month
      - month

  Pricing:
    description: Pricing created by converting an array to product
    type: object
    properties:
      id:
        description: Unique ID of plan as defined by Stripe
        type: string
        example: "planID"
      array_uuid:
        description: Unique ID of registered array
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      pricing_name:
        description: Name of pricing
        type: string
      pricing_type:
        description: Type of pricing
        $ref: "#/definitions/PricingType"
      product_name:
        description: Name of product
        type: string
      product_statement_descriptor:
        description: Extra information about a product which will appear on the credit card statement of the customer
        type: string
      product_unit_label:
        description: A label that represents units of this product in Stripe and receipts and invoices of the customer
        $ref: "#/definitions/PricingUnitLabel"
      currency:
        description: Currency of pricing
        $ref: "#/definitions/PricingCurrency"
      aggregate_usage:
        description: Specifies a usage aggregation strategy for pricings of usage_type=metered
        $ref: "#/definitions/PricingAggregateUsage"
      interval:
        description: The frequency with which a subscription should be billed
        $ref: "#/definitions/PricingInterval"
      divided_by:
        description: Group of n product unit labels
        type: integer
        format: int64
        example: 1048576
      charge:
        description: Price in cents (decimal) per unitlabel
        type: number
        format: double
      activated:
        description: If pricing is activated
        type: boolean
        example: false

  Subscription:
    description: Subscription of a user (customer) to another user's arrays
    type: object
    properties:
      id:
        description: Unique ID of subscription as defined by Stripe
        type: string
        example: "subscriptionID"
      owner_namespace_uuid:
        description: Unique ID of the array (product) owner
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      customer_namespace_uuid:
        description: Unique ID of the array (product) user (customer)
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      pricing:
        description: list of pricing used by this subscription
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Pricing"

  ArrayInfo:
    description: metadata of an array
    type: object
    properties:
      id:
        description: unique ID of registered array
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      file_type:
        description: File type stored /wrapped by this array
        x-omitempty: true
        $ref: "#/definitions/FileType"
      file_properties:
        type: object
        description: map of file properties created for this array
        x-omitempty: true
        additionalProperties:
          type: string
      uri:
        description: uri of array
        type: string
        example: "s3://bucket/array"
      namespace:
        description: namespace array is in
        type: string
        example: "user1"
      size:
        description: size in bytes of array
        type: number
        format: uint64
        example: 1024
        x-nullable: true
      last_accessed:
        description: Datetime array was last accessed in UTC
        type: string
        format: date-time
      description:
        description: description of array
        type: string
        x-nullable: true
      name:
        description: name of array
        type: string
        example: myarray1
      allowed_actions:
        description: list of actions user is allowed to do on this array
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActions"
      pricing:
        description: list of pricing created for this array
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Pricing"
      subscriptions:
        description: list of subscriptions created for this array
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Subscription"
      logo:
        description: logo (base64 encoded) for the array. Optional
        type: string
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used
        type: string
      type:
        description: Array type (dense, key-value, sparse). Calculation of array type runs after array has been registered. So, it is not available immediately.
        example: sparse
        x-nullable: true
        $ref: "#/definitions/ArrayType"
      share_count:
        description: number of unique namespaces this array is shared with
        type: number
        format: int32
      public_share:
        description: Suggests if the array was shared to public by owner
        type: boolean
        x-omitempty: false
        example: true
      namespace_subscribed:
        description: Depends on the namespace asking, denotes the existence of subscription of namespace to this array
        type: boolean
        readOnly: true
        example: false
      tiledb_uri:
        description: uri for access through TileDB cloud
        type: string
        x-omitempty: false
      tags:
        description: optional tags for array
        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
      read_only:
        description: Suggests if the array is in read_only mode
        type: boolean
        x-nullable: true
        example: false
      is_favorite:
        description: Indicates whether the array is in user favorites
        type: boolean
        x-omitempty: true
        example: true

  ArrayInfoUpdate:
    description: metadata of an array
    type: object
    properties:
      description:
        description: description of array
        type: string
        x-nullable: true
      name:
        description: description of array
        type: string
        example: myarray1
      uri:
        description: uri of array
        type: string
        example: "s3://bucket/array"
      file_type:
        description: File type stored /wrapped by this array
        x-omitempty: true
        $ref: "#/definitions/FileType"
      file_properties:
        type: object
        description: map of file properties created for this array
        x-omitempty: true
        additionalProperties:
          type: string
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used
        type: string
      logo:
        description: logo (base64 encoded) for the array. Optional
        type: string
      tags:
        description: optional tags for array
        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
      read_only:
        description: Suggests if the array is in read_only mode
        type: boolean
        x-omitempty: true
        example: true

  TokenRequest:
    description: A request from a user for an api token
    type: object
    properties:
      expires:
        description: Expiration date for token, if empty token defaults to 30 minutes
        type: string
        format: date-time
        example: 2018-12-31T12:13:14Z
      name:
        description: Optional name for token, if the name already exists for the user it will be auto incremented (i.e. myToken-1)
        type: string
        example: myToken
      scope:
        description: "Optional scope to limit token, defaults to all permissions, current supported values are password_reset or *"
        type: array
        items:
          $ref: "#/definitions/TokenScope"

  Token:
    description: A api token and its metadata
    type: object
    properties:
      token:
        description: A api token
        type: string
      name:
        description: Name of token to revoke
        type: string
      issued_at:
        description: datetime the token was created
        type: string
        format: date-time
      expires_at:
        description: datetime the token when token will expire
        type: string
        format: date-time
      scope:
        description: Optional scope to limit token, defaults to all permissions, current supported values are password_reset or *
        type: array
        items:
          $ref: "#/definitions/TokenScope"

  AWSAccessCredentials:
    description: Model representing aws keys or service role, service roles are currently ignored, but will be preferred option in the future
    type: object
    properties:
      secret_access_key:
        type: string
        description: aws secret access key, never returned in get requests
      access_key_id:
        type: string
        description: aws access key
      service_role_arn:
        type: string
        description: aws service role to use for access
      name:
        type: string
        description: human readable name
      default:
        type: boolean
        description: true if this is the default credential to be used within this namespace
        x-omitempty: true
      buckets:
        description: a whitelist of one or more buckets this key should access
        type: array
        x-omitempty: true
        items:
          type: string
          description: A bucket or path of a bucket that is granted access by these credentials
          example: "s3://company-bucket-1/tiledb/"
      created_at:
        description: Time when UDF dependencies were created (rfc3339)
        type: string
        format: date-time
        readOnly: true
      updated_at:
        description: Time when UDF dependencies was last updated (rfc3339)
        type: string
        format: date-time
        readOnly: true

  SSOProvider:
    description: Single sign on provider
    type: string
    enum:
      # Github
      - github
      # Google
      - google
      # Stripe
      - stripe
      # Okta
      - okta

  PublicShareFilter:
    description: Query parameter to get array metadatas
    type: string
    enum:
      # Exclude
      - exclude
      # Only
      - only

  DimensionCoordinate:
    description: A single, typed coordinate for a dimension
    type: object
    properties:
      int8:
        type: integer
        format: int8
        x-omitempty: false
      uint8:
        type: integer
        format: uint8
        x-omitempty: false
      int16:
        type: integer
        format: int16
        x-omitempty: false
      uint16:
        type: integer
        format: uint16
        x-omitempty: false
      int32:
        type: integer
        format: int32
        x-omitempty: false
      uint32:
        type: integer
        format: uint32
        x-omitempty: false
      int64:
        type: integer
        format: int64
        x-omitempty: false
      uint64:
        type: integer
        format: uint64
        x-omitempty: false
      float32:
        type: number
        format: float
        x-omitempty: false
      float64:
        type: number
        format: double
        x-omitempty: false

  UDFSubarrayRange:
    description: A dimension range to query
    type: object
    properties:
      dimension_id:
        type: integer
        description: The dimension index
        x-omitempty: false
      range_start:
        $ref: "#/definitions/DimensionCoordinate"
        description: The range start index
        x-omitempty: false
      range_end:
        $ref: "#/definitions/DimensionCoordinate"
        description: The range end index
        x-omitempty: false

  UDFSubarray:
    description: Subarray bounds to query for a UDF to operate on
    type: object
    properties:
      layout:
        $ref: "#/definitions/Layout"
      ranges:
        description: List of ranges,
        type: array
        items:
          $ref: "#/definitions/UDFSubarrayRange"

  QueryRanges:
    description: Subarray bounds to query
    type: object
    properties:
      layout:
        $ref: "#/definitions/Layout"
      ranges:
        description: List of ranges,
        type: array
        x-omitempty: true
        items:
          type: array
          x-omitempty: true
          items:
            type: number

  QueryJson:
    description: Query returning results as JSON
    type: object
    properties:
      query_ranges:
        description: ranges to run against, generic format
        $ref: "#/definitions/QueryRanges"
      fields:
        description: List of fields to return data from, empty means return data for all fields
        type: array
        x-omitempty: true
        items:
          type: string
          x-omitempty: true

  GenericUDF:
    description: User-defined function
    type: object
    properties:
      udf_info_name:
        type: string
        description: name of UDFInfo to run, format is {namespace}/{udf_name}. Can not be used with exec
        example: TileDB-Inc/csv_ingestor
      language:
        $ref: "#/definitions/UDFLanguage"
        description: UDF language
      version:
        type: string
        description: Type-specific version
      image_name:
        type: string
        description: Docker image name to use for UDF
        x-omitempty: true
      access_credentials_name:
        description: The name of the access credentials to use. if unset, no credentials will be configured in the environment.
        type: string
      resource_class:
        type: string
        description: >
          The resource class to use for the UDF execution. Resource classes define resource limits for memory and CPUs.
          If this is empty, then the UDF will execute in the standard resource class of the TileDB Cloud provider.
        x-omitempty: true
        example: standard
      exec:
        type: string
        description: Type-specific executable text
      exec_raw:
        type: string
        x-omitempty: true
        description: optional raw text to store of serialized function, used for showing in UI
      argument:
        type: string
        description: Argument(s) to pass to UDF function, tuple or list of args/kwargs which can be in native or JSON format
        x-omitempty: true
      stored_param_uuids:
        type: array
        items:
          type: string
          example: 229f38c4-ba89-43d6-ab88-bae3bcca7969
        description: 'The UUIDs of stored input parameters (passed in a
          language-specific format within "argument") to be retrieved from the
          server-side cache. Serialized in standard hex format with no {}.'
      result_format:
        $ref: "#/definitions/ResultFormat"
        description: type of results (native, i.e cloud pickle or json or arrow)
        x-omitempty: true
      task_name:
        description: name of task, optional
        type: string
      store_results:
        description: store results for later retrieval
        type: boolean
      timeout:
        description: "UDF-type timeout in seconds (default: 900)"
        type: integer
      dont_download_results:
        description: 'Set to true to avoid downloading the results of this UDF.
          Useful for intermediate nodes in a task graph where you will not be
          using the results of your function.
          Defaults to false ("yes download results").'
        type: boolean
      task_graph_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the ID of the log for the task graph that this was part of.
      client_node_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the client-defined ID of the node within this task's graph.

  UDFArrayDetails:
    description: Contains array details for multi-array query including uri, ranges buffers
    type: object
    properties:
      parameter_id:
        description: >
          An optional client-generated identifier to distinguish between
          multiple range/buffer requests from the same array in the same call.

          This may be set for MultiArrayUDFs that use the `argument_json` style
          of passing arrays.
        type: string
        x-nullable: true
        x-omitempty: true
      uri:
        description: array to set ranges and buffers on, must be in tiledb:// format
        type: string
      ranges:
        description: ranges to run against, generic format
        $ref: "#/definitions/QueryRanges"
      buffers:
        description: List of buffers to fetch (attributes + dimensions)
        type: array
        x-omitempty: true
        items:
          type: string

  MultiArrayUDF:
    description: User-defined function
    type: object
    properties:
      udf_info_name:
        type: string
        description: name of UDFInfo to run, format is {namespace}/{udf_name}. Can not be used with exec
        example: TileDB-Inc/quickstart_median
      language:
        $ref: "#/definitions/UDFLanguage"
        description: UDF language
      version:
        type: string
        description: Type-specific version
      image_name:
        type: string
        description: Docker image name to use for UDF
        x-omitempty: true
      access_credentials_name:
        description: The name of the access credentials to use. if unset, no credentials will be configured in the environment.
        type: string
      resource_class:
        type: string
        description: >
          The resource class to use for the UDF execution. Resource classes define resource limits for memory and CPUs.
          If this is empty, then the UDF will execute in the standard resource class of the TileDB Cloud provider.
        x-omitempty: true
        example: standard
      exec:
        type: string
        description: Type-specific executable text
      exec_raw:
        type: string
        x-omitempty: true
        description: optional raw text to store of serialized function, used for showing in UI
      result_format:
        $ref: "#/definitions/ResultFormat"
      task_name:
        description: name of task, optional
        type: string
      argument:
        type: string
        description: >
          Deprecated: Prefer to use `argument_json` instead.

          Argument(s) to pass to UDF function, tuple or list of args/kwargs
          which can be in native or JSON format
        x-omitempty: true
      arguments_json:
        type: array
        description: >
          A series of key-value pairs to be passed as arguments into the UDF.
          See `TGUDFNodeData.arguments` for more information.

          If this format is used to pass arguments, arrays will be passed into
          the UDF as specified by the Node placeholders passed in here, rather
          than the classic method of putting all array arguments in the first
          parameter.

          Either this or `argument` should be set.
        items:
          $ref: "#/definitions/TGUDFArgument"
        x-nullable: true
      stored_param_uuids:
        type: array
        items:
          type: string
        description: 'The UUIDs of stored input parameters (passed in a
          language-specific format within "argument") to be retrieved from the
          server-side cache. Serialized in standard hex format with no {}.'
      store_results:
        description: store results for later retrieval
        type: boolean
      dont_download_results:
        description: 'Set to true to avoid downloading the results of this UDF.
          Useful for intermediate nodes in a task graph where you will not be
          using the results of your function.
          Defaults to false ("yes download results").'
        type: boolean
      ranges:
        description: ranges to run against, generic format. Deprecated please set arrays with UDFArrayDetails
        $ref: "#/definitions/QueryRanges"
      subarray:
        $ref: "#/definitions/UDFSubarray"
        description: Subarray ranges to query. This is deprecated. For single-array UDF, please use `ranges` in `MultiArrayUDF`; for multi-array UDF, please use `ranges` in `UDFArrayDetails`.
      buffers:
        description: List of buffers to fetch (attributes + dimensions). Deprecated; please set arrays with `UDFArrayDetails`.
        type: array
        x-omitempty: true
        items:
          type: string
      arrays:
        description: Array ranges/buffer into to run UDF on
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/UDFArrayDetails"
      timeout:
        description: "UDF-type timeout in seconds (default: 900)"
        type: integer
      task_graph_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the ID of the log for the task graph that this was part of.
      client_node_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the client-defined ID of the node within this task's graph.

  UDFImage:
    description: Defines a set of images related to a specific name
    type: object
    properties:
      id:
        description: Unique ID of set of images
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      name:
        type: string
        description: name of UDF
      language:
        $ref: "#/definitions/UDFLanguage"
        description: UDF language

  UDFImageVersion:
    description: Defines an image that belongs to a set of images having a version
    type: object
    properties:
      id:
        description: Unique ID of a versioned image
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      name:
        type: string
        description: name of UDFImageVersion
      udf_image_uuid:
        description: Unique ID of the UDF image set
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      docker_image:
        type: string
        description: Uri of docker image related to current entry
      version:
        description: Image-specific version
        type: number
        format: uint64
        example: 2
      default:
        description: If current image is default version
        type: boolean
        example: true
      latest:
        description: If current image is latest version
        type: boolean
        example: true

  UDFInfoUpdate:
    description: User-defined function that can persist in db, used and shared multiple times
    type: object
    properties:
      name:
        type: string
        description: name of UDF
      language:
        $ref: "#/definitions/UDFLanguage"
        description: UDF language
      version:
        type: string
        description: Type-specific version
      image_name:
        type: string
        description: Docker image name to use for UDF
        x-omitempty: true
      type:
        $ref: "#/definitions/UDFType"
        description: UDF type
      exec:
        type: string
        description: Type-specific executable text
      exec_raw:
        type: string
        x-omitempty: true
        description: optional raw text to store of serialized function, used for showing in UI
      readme:
        type: string
        description: Markdown readme of UDFs
      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
      tags:
        description: optional tags for UDF
        x-omitempty: false
        type: array
        items:
          type: string
          description: tag must be lowercase characters or hypen [a-z-]

  UDFInfo:
    description: User-defined function that can persist in db, used and shared multiple times
    type: object
    properties:
      id:
        description: Unique ID of UDF
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      name:
        type: string
        description: name of UDF
      language:
        $ref: "#/definitions/UDFLanguage"
        description: UDF language
      type:
        $ref: "#/definitions/UDFType"
        description: UDF type
      readme:
        type: string
        description: Markdown readme of UDFs
      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
      tags:
        description: optional tags for UDF
        x-omitempty: false
        type: array
        items:
          type: string
          description: tag must be lowercase characters or hypen [a-z-]

  SQLParameters:
    description: Parameters for running sql query
    type: object
    properties:
      name:
        description: name of task, optional
        type: string
      query:
        description: query to run
        type: string
      output_uri:
        type: string
        description: Output array uri
        example: "s3://my_bucket/my_output_array"
      store_results:
        description: store results for later retrieval
        type: boolean
      dont_download_results:
        description: 'Set to true to avoid downloading the results of this UDF.
          Useful for intermediate nodes in a task graph where you will not be
          using the results of your function.
          Defaults to false ("yes download results").'
        type: boolean
      resource_class:
        type: string
        description: >
          The resource class to use for the SQL execution. Resource classes define resource limits for memory and CPUs.
          If this is empty, then the SQL will execute in the standard resource class of the TileDB Cloud provider.
        x-omitempty: true
        example: standard
      result_format:
        $ref: "#/definitions/ResultFormat"
        description: type of results (native, i.e cloud pickle or json or arrow)
        x-omitempty: tru
      init_commands:
        description: Queries or commands to run before main query
        type: array
        items:
          type: string
          description: sql query or command to run before main sql query
      parameters:
        description: SQL query parameters
        type: array
        items: {}
      task_graph_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the ID of the log for the task graph that this was part of.
      client_node_uuid:
        type: string
        x-omitempty: true
        description: >
          If set, the client-defined ID of the node within this task's graph.

  NotebookStatus:
    description: Status details of a notebook server
    type: object
    properties:
      namespace:
        description: namespace of notebook
        type: string
      uptime:
        description: duration notebook has been running in seconds
        type: integer
        format: uint64
        example: 120
      cpu_usage:
        description: current cpu usage in millicpu
        type: integer
        format: uint64
        example: 4000
      gpu_usage:
        description: gpu usage in milligpu
        type: integer
        format: uint64
        example: 4000
      memory_usage:
        description: memory usage in bytes
        type: integer
        format: uint64
        example: 1073741824
      gpu_limit:
        description: gpu limit in milligpu
        type: integer
        format: uint64
        example: 1073741824
      memory_limit:
        description: memory allocated to notebook server in bytes
        type: integer
        format: uint64
        example: 1073741824
      storage_usage:
        description: storage usage in bytes
        type: integer
        format: uint64
        example: 1073741824
      storage_limit:
        description: storage allocated to notebook server in bytes
        type: integer
        format: uint64
        example: 1073741824
      cpu_count:
        description: millicpu allocated to notebook server
        type: integer
        format: uint64
        example: 4000
      cost:
        description: cost in USD for the current notebook session 
        x-omitempty: true
        x-nullable: true
        type: number
        format: double
        example: 0.27

  ArrayFavorite:
    description: A user-favorite array item
    type: object
    properties:
      array_uuid:
        description: unique UUID of the array
        type: string
      namespace:
        description: the namespace of the array
        type: string
      name:
        description: the name of the array
        type: string

  ArrayFavoritesData:
    description: Object including array favorites and pagination metadata
    type: object
    properties:
      arrays:
        description: List of array infos
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/ArrayInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  NotebookFavorite:
    description: A user-favorite notebook item
    type: object
    properties:
      notebook_uuid:
        description: unique UUID of the notebook
        type: string
      namespace:
        description: the namespace of the notebook
        type: string
      name:
        description: the name of the notebook
        type: string

  NotebookFavoritesData:
    description: Object including notebook favorites and pagination metadata
    type: object
    properties:
      notebooks:
        description: List of notebook infos
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/ArrayInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  UDFFavorite:
    description: A user-favorite UDF item
    type: object
    properties:
      udf_uuid:
        description: unique UUID of the UDF
        type: string
      namespace:
        description: the namespace of the UDF
        type: string
      name:
        description: the name of the UDF
        type: string

  UDFFavoritesData:
    description: Object including UDF favorites and pagination metadata
    type: object
    properties:
      udfs:
        description: List of UDF infos
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/ArrayInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  MLModelFavorite:
    description: A user-favorite MLModel item
    type: object
    properties:
      mlmodel_uuid:
        description: unique UUID of the MLModel
        type: string
      namespace:
        description: the namespace of the MLModel
        type: string
      name:
        description: the name of the MLModel
        type: string

  MLModelFavoritesData:
    description: Object including MLModel favorites and pagination metadata
    type: object
    properties:
      mlmodels:
        description: List of MLModel infos
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/ArrayInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  InvitationType:
    description: List of values that InvitationType can take
    type: string
    enum:
      # Array share
      - ARRAY_SHARE
      # Group share
      - GROUP_SHARE
      # Join Organization
      - JOIN_ORGANIZATION

  InvitationStatus:
    description: List of values that InvitationStatus can take
    type: string
    enum:
      # Pending
      - PENDING
      # Accepted
      - ACCEPTED

  InvitationArrayShareEmail:
    description: Encapsulates information regarding inviting people using email to share array, same permissions for all invitees
    type: object
    required:
      - actions
      - invitee_email
    properties:
      actions:
        description: List of permitted actions
        type: array
        items:
          $ref: "#/definitions/ArrayActions"
        example:
          - read
          - write
      invitee_email:
        type: array
        x-omitempty: true
        items:
          type: string

  InvitationFailedRecipients:
    description: Encapsulates information regarding the failed invitation recipients
    type: object
    required:
      - failed_recipients
    properties:
      failed_recipients:
        type: array
        x-omitempty: true
        items:
          type: string

  InvitationGroupShareEmail:
    description: Encapsulates information regarding inviting people using email to share group, same permissions for all invitees
    type: object
    required:
      - array_actions
      - group_actions
      - invitee_email_or_name
    properties:
      array_actions:
        description: List of permitted array actions
        type: array
        items:
          $ref: "#/definitions/ArrayActions"
        example:
          - read
          - write
      group_actions:
        description: List of permitted group actions
        type: array
        items:
          $ref: "#/definitions/GroupActions"
        example:
          - read
          - write
      invitee_email_or_name:
        type: array
        x-omitempty: true
        items:
          type: string

  InvitationOrganizationJoinEmail:
    description: Encapsulates information regarding inviting people using email to join organization, same permissions for all invitees
    type: object
    required:
      - invitee_email
      - organization_role
    properties:
      actions:
        description: List of permitted actions
        type: array
        items:
          $ref: "#/definitions/NamespaceActions"
        example:
          - read
          - write
      organization_role:
        description: Role of the invited namespace in the joined organization
        $ref: "#/definitions/OrganizationRoles"
        x-omitempty: false
      invitee_email:
        type: array
        x-omitempty: true
        items:
          type: string

  Invitation:
    description: Invitations to share or collaborate
    type: object
    properties:
      id:
        description: Unique ID of invitation added to magic link
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      invitation_type:
        description: Type of invitation
        $ref: "#/definitions/InvitationType"
        example: array_share
        x-omitempty: false
      owner_namespace_uuid:
        description: Namespace of the owner of the invitation (user or organization)
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      inviter_uuid:
        description: Unique ID of the user that sent the invitation
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      user_namespace_uuid:
        description: Unique ID of the user accepted the invitation
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      organization_user_uuid:
        description: Unique ID of the organization user accepted the invitation
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      organization_name:
        description: Name of the organization, does not persist in database
        type: string
        example: "organization_name"
      organization_role:
        description: Role of the invited namespace in the joined organization
        $ref: "#/definitions/OrganizationRoles"
        x-omitempty: false
      organization_uuid:
        description: Unique ID of the organization whose user(s) accepted the invitation
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      array_uuid:
        description: Unique ID of the array
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      group_uuid:
        description: Unique ID of the group
        type: string
        x-omitempty: false
        example: "00000000-0000-0000-0000-000000000000"
      array_name:
        description: Name of the array, does not persist in database
        type: string
        example: "array_name"
      email:
        description: Email of the individual we send the invitation to
        type: string
        example: "jane@doe.com"
      actions:
        description: A comma separated list of ArrayActions or NamespaceActions
        type: string
        example: "read,write"
      group_actions:
        description: A comma separated list of GroupActions
        type: string
        example: "read,write"
      status:
        description: Status of invitation
        $ref: "#/definitions/InvitationStatus"
        example: PENDING
        x-omitempty: false
      created_at:
        description: Datetime the invitation was created in UTC
        type: string
        format: date-time
        x-omitempty: false
      expires_at:
        description: Datetime the invitation is expected to expire in UTC
        type: string
        format: date-time
        x-omitempty: false
      accepted_at:
        description: Datetime the invitation was accepted in UTC
        type: string
        format: date-time
        x-omitempty: false
      namespace_invited:
        description: The namespace invited (user or organization, if it exists in the DB)
        type: string
        x-omitempty: true

  InvitationData:
    description: Object including invitations and metadata
    type: object
    properties:
      invitations:
        description: List of invitations
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/Invitation"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  TokenScope:
    description: An api token scope available for creation
    type: string
    enum:
      - password_reset
      - confirm_email
      - "*"
      - user:read
      - user:read-write
      - user:admin
      - array:read
      - array:read-write
      - array:admin
      - organization:read
      - organization:read-write
      - organization:admin
      - group:read
      - group:read-write
      - group:admin

  FileCreate:
    description: Input/Output information required to create a new file
    type: object
    properties:
      input_uri:
        type: string
        description: storage URI of the input file
      output_uri:
        type: string
        description: output location of the TileDB File
      name:
        type: string
        description: name to set for registered file

  FileCreated:
    description: Created file name and information
    type: object
    properties:
      output_uri:
        type: string
        description: output location of the TileDB File
      file_name:
        type: string
        description: name of the file created

  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

  FileExport:
    description: Output information required to export a file
    type: object
    properties:
      output_uri:
        type: string
        description: output location of the TileDB File

  FileExported:
    description: Output uri of the exported file
    type: object
    properties:
      output_uri:
        type: string
        description: output location of the exported file

  NotebookCopy:
    description: Output information required to copy a notebook
    type: object
    properties:
      output_uri:
        type: string
        description: output location of the TileDB File
      name:
        type: string
        description: name to set for registered notebook
      namespace:
        type: string
        description: namespace to copy to

  NotebookCopied:
    description: Copied notebook uri 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 created
      namespace:
        type: string
        description: namespace copied to
      id:
        description: unique ID of the copied notebook
        type: string
        example: "00000000-0000-0000-0000-000000000000"
        x-omitempty: false

  UDFCopy:
    description: information required to copy a udf
    type: object
    properties:
      output_uri:
        type: string
        description: output location of the TileDB File
      namespace:
        type: string
        description: namespace to register the copy. If empty use the namespace of the request user
      name:
        type: string
        description: name to set for the copy. If empty use the name as the original udf, if it not already used in the namespace

  UDFCopied:
    description: Copied udf uri and information
    type: object
    required:
      - id
    properties:
      output_uri:
        type: string
        description: output location of the TileDB udf
      namespace:
        type: string
        description: namespace of the copied udf
      name:
        type: string
        description: name of the copied udf
      id:
        description: unique ID of the copied udf
        type: string
        example: "00000000-0000-0000-0000-000000000000"
        x-omitempty: false

  GroupActions:
    description: actions a user can take on a group
    type: string
    enum:
      # Read: read contents
      - read
      # Write: add a new asset
      - write
      # Edit: update attributes, add and remove assets
      - edit

  GroupType:
    description: Group type is a hint for the groups contents and TileDB Cloud may use a specialized viewer for each type
    type: string
    enum:
      # Generic
      - generic
      # VCF
      - vcf
      # SOMA
      - soma
      # Biomedical Imaing
      - bioimg
      # Point Cloud
      - pointcloud
      # Raster
      - raster
      # Geometry
      - geometry
      # Vector search
      - vector_search

  GroupTypeMetadataKey:
    description: A group type is stored in the group metadata using this key
    type: string
    enum:
      - dataset_type

  GroupInfo:
    description: metadata of a group
    type: object
    properties:
      id:
        description: unique ID of registered group
        type: string
        example: "00000000-0000-0000-0000-000000000000"
      namespace:
        description: namespace group is in
        type: string
        example: "user1"
      name:
        description: name of group
        type: string
        example: myarray1
      description:
        description: description of group
        type: string
        x-nullable: true
      uri:
        description: uri of group
        type: string
        example: "s3://bucket/asset"
      tiledb_uri:
        description: uri for access through TileDB cloud
        type: string
        x-omitempty: false
      asset_count:
        description: A count of direct array members
        type: number
        format: int32
        example: 12
        x-omitempty: false
      group_count:
        description: A count of direct group members
        type: number
        format: int32
        example: 4
        x-omitempty: false
      size:
        description: A count of direct members. This is the sum of asset_count and group_count
        type: number
        format: int32
        example: 16
        x-omitempty: false
      last_accessed:
        description: Datetime groups was last accessed in UTC
        type: string
        format: date-time
      allowed_actions:
        description: list of actions user is allowed to do on this group
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/GroupActions"
      group_type:
        description: the type of the group
        $ref: "#/definitions/GroupType"
        x-omitempty: true
      logo:
        description: logo (base64 encoded) for the gruop. Optional
        type: string
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used
        type: string
      share_count:
        description: number of unique namespaces this group is shared with
        type: number
        format: int32
      public_share:
        description: Suggests if the group was shared to public by owner
        type: boolean
        x-omitempty: false
        example: true
      tags:
        description: optional tags for group
        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

  GroupEntry:
    description: Object describing a single member of a group, which can be an array or a group
    type: object
    properties:
      member_id:
        type: string
        readOnly: true
        description: The unique member id for the entry
      group:
        description: the metadata of the entry if it is a group, null if it is an array
        $ref: "#/definitions/GroupInfo"
      array:
        description: the metadata of the entry if it is an array, null if it is a group
        $ref: "#/definitions/ArrayInfo"

  GroupContents:
    description: Object including a page of members of a group and pagination metadata
    type: object
    properties:
      entries:
        description: Groups members
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/GroupEntry"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  GroupBrowserData:
    description: Object including group info and pagination metadata
    type: object
    properties:
      groups:
        description: Groups Info
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/GroupInfo"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  GroupBrowserFilterData:
    description: Object with data to fill browser filter
    type: object
    properties:
      namespaces:
        description: list of all unique namespaces to display
        type: array
        x-omitempty: false
        items:
          type: string
      group_types:
        description: list of all available group types to display
        type: array
        x-omitempty: false
        items:
          $ref: "#/definitions/GroupType"

  GroupContentsFilterData:
    description: Object with data to fill contents filter
    type: object
    properties:
      namespaces:
        description: list of all unique namespaces to display
        type: array
        x-omitempty: false
        items:
          type: string

  GroupCreate:
    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
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used.
        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

  GroupRegister:
    description: Initial attributes for the registration of a an existing 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
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used.
        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

  GroupUpdate:
    description: Updates for a group. New values for the attributes.
    type: object
    properties:
      description:
        description: A human readable description of the content of the group
        type: string
        x-nullable: true
      name:
        description: The name of the group. If must be unique within the group.
        type: string
      logo:
        description: logo (base64 encoded) for the group. Optional
        type: string
      access_credentials_name:
        description: the name of the access credentials to use. if unset, the default credentials will be used
        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

  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:
      namespace:
        description: The namespace of the asset.
        type: string
      name:
        description: The name or id of the asset.
        type: string
      member_type:
        $ref: "#/definitions/GroupMemberType"

  GroupChanges:
    description: A request to change the members of a group. Contains assets to add or remove.
    type: object
    properties:
      add:
        description: the assets, arrays or groups, to add to the group.
        type: array
        items:
          $ref: "#/definitions/GroupMember"
      remove:
        description: the assets, arrays or groups, to remove from the group.
        type: array
        items:
          $ref: "#/definitions/GroupMember"

  GroupSharing:
    description: sharing state of a group with a namespace
    type: object
    properties:
      group_actions:
        description: List of permitted actions for the group and all subgroups
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/GroupActions"
        example:
          - read
          - write
      array_actions:
        description: List of permitted actions for all the subarrays of the group
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActions"
        example:
          - read
          - write
      namespace:
        description: namespace being granted group access can be a user or organization
        type: string
        example: "MyOrganization"
      namespace_type:
        description: details on if the namespace is a organization or user
        type: string
        example: "organization"

  GroupSharingRequest:
    description: a request to share a group and all the contents with a namespace
    type: object
    properties:
      group_actions:
        description: List of permitted actions for the group and all subgroups
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/GroupActions"
        example:
          - read
          - write
      array_actions:
        description: List of permitted actions for all the subarrays of the group
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/ArrayActions"
        example:
          - read
          - write
      namespace:
        description: namespace being granted group access can be a user or organization
        type: string
        example: "MyOrganization"

  GroupActivity:
    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
        $ref: "#/definitions/ArrayActivityLog"

  GroupActivityResponse:
    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
        x-nullable: false
        items:
          $ref: "#/definitions/GroupActivity"
      pagination_metadata:
        x-omitempty: false
        x-nullable: false
        $ref: "#/definitions/PaginationMetadata"

  #
  # Task graph messages
  #

  # Task graph logs

  TaskGraphLogRunLocation:
    description: >
      The location where an individual node of a task graph is executed.
    type: string
    enum:
      - server
      # The node is executed server-side. This node will appear in the
      # ArrayTask logs.
      - client
        # The node is executed client-side. This node will NOT appear in the
        # ArrayTask logs since no action will have been performed.
      - virtual
        # The node is not executed at all. This node represents an input or
        # other node that is a component of the graph but is not a true step
        # that actually executes code.

  TaskGraphLogStatus:
    description: The status of a given task graph execution.
    type: string
    enum:
      - submitted
        # The task graph has been submitted, but no tasks have been run.
        # This should not be reported by the client.
      - running
        # Some task in the graph is currently running.
        # This should not be reported by the client.
      - idle
        # The graph is not yet completed, but nothing is actively running.
        # This should not be reported by the client.
      - abandoned
        # The graph has been idle for an extended period of time, likely due to
        # the client crashing or aborting without notifying the server.
        # Semantically this is equivalent to `idle`.
      - succeeded
        # The client has declared that the task graph has completed
        # successfully. This ordinarily entails all nodes succeeding.
      - failed
        # The client has declared that the task graph was not successful.
      - cancelled
        # The client has cancelled further execution of the task graph.

  TaskGraphType:
    description: >
      The type of a task graph.
    type: string
    enum:
      - batch
      - realtime

  TaskGraphLog:
    description: Logging information about the execution of a task graph.
    type: object
    properties:
      uuid:
        type: string
        readOnly: true
        description: The server-generated UUID of the task graph.
      namespace:
        type: string
        description: >
          The namespace that owns this task graph log.
          When creating a task graph log, this is used as the namespace to
          create the log in; thereafter it is read-only.
      created_by:
        type: string
        readOnly: true
        description: The name of the user who created this task graph log.
      name:
        type: string
        description: >
          A name for this task graph log, displayed in the UI.
          Does not need to be unique.
      created_at:
        type: string
        format: date-time
        readOnly: true
        description: >
          The date/time when this task graph log was originally created.
          This is distinct from the execution start_time.
      start_time:
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
        x-omitempty: true
        description: >
          The start time of the task graph, recorded when the server
          starts executing the first node.
      end_time:
        type: string
        format: date-time
        readOnly: true
        x-nullable: true
        x-omitempty: true
        description: >
          The end time of the task graph, recorded when the client reports
          completion.
      status:
        $ref: "#/definitions/TaskGraphLogStatus"
      total_cost:
        type: number
        x-nullable: true
        description: >
          If present, the total cost of executing all nodes in this task graph.
      access_cost:
        type: number
        x-nullable: true
        description: >
          If present, the total cost of access from execution of the nodes
          in this task graph.
      egress_cost:
        type: number
        x-nullable: true
        description: >
          If present, the total cost of access from execution of the nodes
          in this task graph.
      execution_time:
        type: string
        description: >
          The total execution time of all the nodes in this graph, in ISO 8601
          format with hours, minutes, and seconds.
        example: "P15H22M0.45S"
      status_count:
        type: object
        description: >
          A mapping from `ArrayTaskStatus` string value to the number of nodes
          in this graph that are in that status.
        additionalProperties:
          description: The number of nodes that are in the given state.
          type: number
      nodes:
        type: array
        items:
          $ref: "#/definitions/TaskGraphNodeMetadata"
        description: >
          The structure of the graph. This is provided by the client
          when first setting up the task graph. Thereafter, it is read-only.
          This must be topographically sorted; that is, each node must appear
          after all nodes that it depends upon.
      task_graph_type:
        $ref: "#/definitions/TaskGraphType"
      task_graph_id:
        type: string
        description: The UUID of the task graph.

  TaskGraphNodeMetadata:
    description: Metadata about an individual node in a task graph.
    type: object
    properties:
      client_node_uuid:
        type: string
        description: The client-generated UUID of the given graph node.
      name:
        type: string
        description: >
          The client-generated name of the node.
          This is not guaranteed to be unique.
      depends_on:
        type: array
        items:
          type: string
        description: >
          The client_node_uuid of each node that this node depends upon.
          Used to define the structure of the graph.
      run_location:
        $ref: "#/definitions/TaskGraphLogRunLocation"
      status:
        description: >
          If present, the overall execution status of this node, taking into
          account the latest execution information.

          For nodes that have not yet been executed, this will be listed as
          `QUEUED`. For nodes that are set to run locally and have not reported
          any status information, this will be listed as `UNKNOWN`.
        $ref: "#/definitions/ArrayTaskStatus"
      status_message:
        description: The reason the array task status is in the state
        type: string
        x-nullable: true
        x-omitempty: true
      executions:
        type: array
        items:
          $ref: "#/definitions/ArrayTask"
        readOnly: true
        description: >
          ArrayTasks representing each execution attempt for this node.
          For nodes that have never been submitted, this will be empty.
          For nodes that have been retried, this may have multiple entries.
          The last one in the list represents the most recent execution.

          This is read-only and generated by the server based on
          the tasks it has actually executed.

  TaskGraphLogsData:
    description: Response data for a task graph list, including pagination metadata.
    type: object
    properties:
      task_graph_logs:
        description: The requested task graph logs.
        type: array
        items:
          $ref: "#/definitions/TaskGraphLog"
      pagination_metadata:
        $ref: "#/definitions/PaginationMetadata"

  TaskGraphClientNodeStatus:
    description: >
      A report of the execution status of a node that ran on the client side.
    type: object
    properties:
      client_node_uuid:
        type: string
      status:
        $ref: "#/definitions/ArrayTaskStatus"

  # Task graph
  TaskGraph:
    description: Information about a task graph.
    type: object
    properties:
      uuid:
        type: string
        readOnly: true
        description: The server-generated UUID of the task graph.
      namespace:
        type: string
        description: >
          The namespace that owns this task graph.
          When creating a task graph log, this is used as the namespace to
          create the log in; thereafter it is read-only.
      created_by:
        type: string
        readOnly: true
        description: The name of the user who created this task graph log.
      name:
        type: string
        description: >
          A name for this task graph, displayed in the UI.
          Does not need to be unique.
      created_at:
        type: string
        format: date-time
        readOnly: true
        description: >
          The date/time when this task graph was originally created.
      nodes:
        type: array
        items:
          $ref: "#/definitions/TaskGraphNode"
        description: >
          The structure of the graph. This is provided by the client
          when first setting up the task graph. 
          This must be topographically sorted; that is, each node must appear
          after all nodes that it depends upon.
      parallelism:
        type: integer
        format: int64
        x-nullable: true
        x-omitempty: true
        description: >
          Parallelism limits the max total parallel pods that can execute
          at the same time in a workflow.
      retry_strategy:
        $ref: '#/definitions/RetryStrategy'
      deadline:
        type: integer
        format: int64
        x-nullable: true
        x-omitempty: true
        description: >
          Duration in seconds relative to the workflow start time which the
          workflow is allowed to run before it gets terminated.
      task_graph_type:
        $ref: "#/definitions/TaskGraphType"

  TaskGraphs:
    description: Information about a series of task graphs.
    type: object
    properties:
      graphs:
        type: array
        items:
          $ref: "#/definitions/TaskGraph"
        description: >
          The series of graphs.

  # Registered task graphs

  RegisteredTaskGraph:
    description: >
      The structure and metadata of a task graph that can be stored
      on TileDB Cloud and executed by users who have access to it.
    type: object
    properties:
      uuid:
        type: string
        description: A server-assigned unique ID for the UDF, in UUID format.
      namespace:
        type: string
        description: The namespace that owns this task graph log.
      name:
        type: string
        description: >
          The name of this graph, to appear in URLs.
          Must be unique per-namespace.
      readme:
        type: string
        description: Documentation for the task graph, in Markdown format.
      license_id:
        type: string
        x-nullable: True
        description: SPDX license identifier.
      license_text:
        type: string
        x-nullable: True
        description: Full text of the license.
      tags:
        type: array
        x-nullable: False
        description: Optional tags to classify the graph.
        items:
          type: string
          description: Unaccented, lowercase, hyphenated Latin characters.
      nodes:
        type: array
        items:
          $ref: '#/definitions/TaskGraphNode'
        description: >
          The structure of the graph, in the form of the nodes that make it up.
          As with `TaskGraphLog`, nodes must topologically sorted, so that any
          node appears after all the nodes it depends on.

  TaskGraphActions:
    description: actions a user can take on a UDF
    type: string
    enum:
      # Fetch task graph
      - fetch_task_graph
      # Share task graph with others
      - share_task_graph

  TaskGraphSharing:
    description: details for sharing a given registered task graph
    type: object
    properties:
      actions:
        description: List of permitted actions
        type: array
        x-omitempty: true
        items:
          $ref: "#/definitions/TaskGraphActions"
        example:
          - fetch_task_graph
          - share_task_graph
      namespace:
        description: namespace being granted array access can be a user or organization
        type: string
        example: "MyOrganization"
      namespace_type:
        description: details on if the namespace is a organization or user
        type: string
        example: "organization"

  TaskGraphNode:
    description: >
      Information about a single node within a registered task graph.
      A single node represents one piece of data or a computational step;
      either as an input value, a data source, or a computation that acts upon
      earlier nodes. The structure parallels the existing
      `TaskGraphNodeMetadata`.
    type: object
    properties:
      client_node_id:
        type: string
        description: The client-generated UUID of the given graph node.
      name:
        type: string
        x-nullable: true
        description: >
          A client-specified name for the node. If provided, this must be
          unique.
      depends_on:
        type: array
        items:
          type: string
        description: >
          The client_node_uuid of each node that this node depends upon.
          Used to define the structure of the graph.
      array_node:
        $ref: "#/definitions/UDFArrayDetails"
      input_node:
        $ref: "#/definitions/TGInputNodeData"
      sql_node:
        $ref: "#/definitions/TGSQLNodeData"
      udf_node:
        $ref: '#/definitions/TGUDFNodeData'
      retry_strategy:
        $ref: '#/definitions/RetryStrategy'
      expand_node_output:
        type: string
        x-nullable: true
        description: >
          Used to create dynamic tasks based on the output of another node.
          The other node's output must be a JSON list of values. The expansion
          process creates one task per item in the output list. The item is
          also passed as an argument to each task. The value is the
          client_node_uuid of the node that we want to expand.
      deadline:
        type: integer
        format: int64
        x-nullable: true
        x-omitempty: true
        description: >
          Duration in seconds relative to the node start time which the
          node is allowed to run before it gets terminated.

  TGArrayNodeData:
    description: >
      The details of an array that should be queried and provided as the input
      to a UDF Node. This is essentially a `UDFArrayDetails`, but you’re allowed
      to provide most of the values as Nodes if you want.
    type: object
    x-nullable: true
    properties:
      uri:
        description: >
          The `tiledb://` URI of the array to query, or a Node which yields
          that `tiledb://` URI.
        $ref: "#/definitions/TGArgValue"
      ranges:
        $ref: "#/definitions/TGQueryRanges"
      buffers:
        description: >
          A list of buffers (attributes and dimensions) to fetch.
          Can be provided either raw or as a node to be interpolated in.
        $ref: "#/definitions/TGArgValue"
        x-omitempty: true

  TGQueryRanges:
    description: Parameterizable version of `QueryRanges`.
    type: object
    properties:
      layout:
        $ref: "#/definitions/Layout"
      friendly_ranges:
        description: >
          The ranges to query against, in a user-friendly format. This is a
          slightly more flexible format designed to be easier for an author
          to use. This may also be Node data which yields these ranges.
          (These will be processed by the client to turn into raw ranges.)

          A single `[lo, hi]` span may be specified as:

          - a scalar value (for `lo == hi`)
          - a Slice (escaped in `"__tdbudf__": "__slice__"` format)
          - a single-entry list (for `lo == hi`)
          - a pair of values `[lo, hi]`

          The ranges for a given dimension may be specified as:

          - a single scalar value (for a single-value `[val, val]` span)
          - a Slice (for exactly one `[lo, hi]` span)
          - a list of spans as described above.

          See the TileDB Cloud documentation for more details on the formats.

          Either this or `ranges` must be specified, but not both.
        $ref: "#/definitions/TGArgValue"
      ranges:
        description: >
          The ranges to query against, or Node data which yields those ranges.

          The result must be in the QueryRanges format:

              [
                [d1lo1, d1hi1, d1lo2, d1hi2, ...],
                [d2lo1, d2hi1, d2lo2, d2hi2, ...],
                ...,
              ]

          but there are many ways to construct it:

          - A node returning the entire `[[lo, hi, ...], ...]` list-of-lists.
          - `[[(lo node), (hi node)], ...]`
          - `[(node returning lo/hi pairs), ...]`
          - Or a mix of any of the above.

          Either this or `user_ranges` must be specified, but not both.
        $ref: "#/definitions/TGArgValue"

  TGInputNodeData:
    description: >
      Specifies that a node is an “input value”, allowing for parameterized
      task graphs. An input node may not depend upon any other nodes.
    type: object
    x-nullable: True
    properties:
      default_value:
        $ref: "#/definitions/TGArgValue"
      datatype:
        description: >
          An annotation of what datatype this node is supposed to be.
          Conventionally, this is a Python-format type annotation,
          but it’s purely for documentation purposes and not validated.
        type: string
        x-nullable: true

  TGSQLNodeData:
    description: >
      A node specifying an SQL query to execute in TileDB Cloud.
    type: object
    x-nullable: true
    properties:
      init_commands:
        description: The commands to execute before running the query itself.
        type: array
        items:
          type: string
      query:
        description: >
          The text of the SQL query to execute. Parameters are substituted in
          for `?`s, just as in a regular MariaDB query.
        type: string
      parameters:
        description: >
          The parameters to substitute in for arguments in the `query`.
          Fixed-length. Arguments must be in JSON format.
        type: array
        items:
          $ref: "#/definitions/TGArgValue"
      result_format:
        $ref: "#/definitions/ResultFormat"
      namespace:
        description: >
          If set, the non-default namespace to execute this SQL query under.
        type: string
        x-nullable: true

  TGUDFNodeData:
    description: A node specifying the execution of a user-defined function.
    type: object
    x-nullable: true
    properties:
      registered_udf_name:
        description: >
          If set, the name of the registered UDF to execute, in the format
          `namespace/name`. Either this or `executable_code` should be set,
          but not both.
        type: string
        x-nullable: true
      executable_code:
        description: >
          If set, the base64 serialization of the code for this step, encoded
          in a language-specific format (e.g. Pickle for Python, serialization
          for R).
        type: string
        x-nullable: true
      source_text:
        description: >
          Optionally, the source text for the code passed in `executable_code`.
          *For reference only; only the code in `executable_code` is actually
          executed.* This will be included in activity logs and may be useful
          for debugging.
        type: string
      environment:
        $ref: "#/definitions/TGUDFEnvironment"
      arguments:
        description: >
          The arguments to a UDF function. This encompasses both named and
          positional arguments. The format is designed to provide compatibility
          across languages like Python which have a fairly traditional split
          between positional arguments and named arguments, and languages like R
          which has a rather unique way of specifying arguments.

          For Python (and most other languages), all positional arguments will
          come before all named arguments (if any are present):

              // fn(arg1, arg2, arg3)
              [
                {value: arg1},
                {value: arg2},
                {value: arg3},
              ]
              // fn(arg1, arg2, n=kw1, a=kw2)
              [
                {value: arg1},
                {value: arg2},
                {name: "n", value: kw1},
                {name: "a", value: kw2},
              ]
              // fn(kw=k1, only=k2)
              [
                {name: "kw", value: k1},
                {name: "only", value: k2},
              ]

          However, in R, named and positional arguments may be intermixed
          freely:

              // fn(arg, n=kw1, arg2)
              [
                {value: arg},
                {name: "n", value: kw1},
                {value: arg2},
              ]
        type: array
        items:
          $ref: "#/definitions/TGUDFArgument"
      result_format:
        $ref: "#/definitions/ResultFormat"


  TGUDFArgument:
    description: >
      A single argument to a UDF. This may represent a positional argument or
      a named argument, depending upon whether `name` is set.
    type: object
    properties:
      name:
        description: The name of the argument, if present.
        type: string
        x-nullable: true
      value:
        $ref: "#/definitions/TGArgValue"

  TGArgValue:
    description: >
      An argument provided to a node. This is one of a direct value (i.e.,
      a raw JSON value) or a `TGSentinel`.

      For example this Python value:

          {"a": [1, "pipe", range(30), None], "b": b"bytes"}

      is encoded thusly (with included comments):

          {  // A dictionary with string keys is JSON-encodable.
            "a": [  // As is a list.
              1,
              "pipe",
              {  // A `range` is replaced with its pickle.
                "__tdbudf__": "immediate",
                "format": "python_pickle",
                "base64_data": "gASVIAAAAAAAAACMCGJ1aWx0aW5zlIwFcmFuZ2WUk5RLAEseSwGHlFKULg=="
              },
              null
            ],
            "b": {  // Raw binary data is encoded into base64.
              "__tdbudf__": "immediate"
              "format": "bytes",
              "base64_data": "Ynl0ZXM="
            }
          }

  TGUDFEnvironment:
    description: Metadata about the environment where we want to execute a UDF.
    type: object
    properties:
      language:
        $ref: "#/definitions/UDFLanguage"
      language_version:
        description: >
          The language version used to execute this UDF. Neither this nor
          `language` needs to be set for registered UDFs, since the language
          and version are stored server-side with the UDF itself.
        type: string
      image_name:
        description: >
          The name of the image to use for the execution environment.
        type: string
      access_credentials_name:
        description: >
          The name of the access credentials to use. if unset, no credentials will be configured in the environment.
        type: string
      namespace:
        description: >
          If set, the non-default namespace to execute this UDF under (and to
          query any Array Nodes that are used as inputs to this UDF).
        type: string
        x-nullable: true
      resource_class:
        description: >
          The resource class to use for the UDF execution. Resource classes
          define resource limits for memory and CPUs. If this is empty, then the
          UDF will execute in the standard resource class of the TileDB Cloud
          provider.
        type: string
        x-omitempty: true
      resources:
        type: object
        description: >
          The resources requested for this particular node. If resources are not 
          specified resource_class is used, if it is not set the standard resource 
          // defaults are used
        properties:
          cpu:
            type: string
            example: 500m
          memory:
            type: string
            example: 8Gi
          gpu:
            type: integer
            example: 1
        x-omitempty: true
      run_client_side:
        description: >
          A hint that, if possible, this function should be executed on the
          client side rather than on the server. Registered UDFs and functions
          which take arrays as inputs can never be executed client-side. If the
          client’s environment is incompatible, or the client does not support
          client-side execution, the function will be executed on the server.
        type: boolean
        x-omitempty: true
      timeout:
        description: >
          The maximum length of time this UDF is allowed to execute for before
          it is killed and fails. If not present (or zero), the function is
          allowed to run indefinitely (subject to the server’s global limits).
        type: number
        x-nullable: true

  FragmentMetadata:
    description: Fragment Metadata
    type: object
    # TODO: define all properties
    properties:
      fileSizes:
        description: fixed sizes
        type: array
        items:
          type: integer
          format: uint64
      fileVarSizes:
        description: var length sizes
        type: array
        items:
          type: integer
          format: uint64
      fileValiditySizes:
        description: validity sizes
        type: array
        items:
          type: integer
          format: uint64
      fragmentUri:
        type: string
      hasTimestamps:
        type: boolean
      hasDeleteMeta:
        type: boolean
      sparseTileNum:
        type: integer
        format: uint64
      tileIndexBase:
        type: integer
        format: uint64
      tileOffsets:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint64
      tileVarOffsets:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint64
      tileVarSizes:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint64
      tileValidityOffsets:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint64
      tileMinBuffer:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      tileMinVarBuffer:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      tileMaxBuffer:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      tileMaxVarBuffer:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      tileSums:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      tileNullCounts:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint64
      fragmentMins:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      fragmentMaxs:
        type: array
        items:
          type: array
          items:
            type: integer
            format: uint8
      fragmentSums:
        type: array
        items:
          type: integer
          format: uint64
      fragmentNullCounts:
        type: array
        items:
          type: integer
          format: uint64
      version:
        type: integer
        format: uint32
      timestampRange:
        type: array
        items:
          type: integer
          format: uint64
      # A pair of timestamps for fragment

      lastTileCellNum:
        type: integer
        format: uint64

      # TODO: handle!
      # nonEmptyDomain @25 :NonEmptyDomainList;
      # non empty domain

      # TODO: handle!
      # rtree @26 :Data;

  SingleFragmentInfo:
    description: Single Fragment info of an array
    type: object
    properties:
      ArraySchemaName:
        description: array schema name
        type: string
      meta:
        description: fragment metadata
        $ref: "#/definitions/FragmentMetadata"

  FragmentInfo:
    description: Fragment info of an array
    type: object
    properties:
      arraySchemaAll:
        description: map of all array schemas
        type: object
        additionalProperties:
          $ref: "#/definitions/ArraySchema"
      fragmentInfo:
        description: information about fragments in the array
        type: array
        items:
          $ref: "#/definitions/SingleFragmentInfo"
      toVacuum:
        description: the URIs of the fragments to vacuum
        type: array
        items:
          type: string

  FragmentInfoRequest:
    description: Fragment info request
    type: object
    properties:
      config:
        description: config to use for opening
        $ref: "#/definitions/TileDBConfig"

  ArrayConsolidationRequest:
    description: Request to consolidate an array
    type: object
    properties:
      config:
        type: object
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"

  ArrayVacuumRequest:
    description: Request to consolidate an array
    type: object
    properties:
      config:
        type: object
        description: config to use to retrieve the contents
        $ref: "#/definitions/TileDBConfig"

  RetryStrategy:
    description: RetryStrategy provides controls on how to retry a taskgraph node
    type: object
    properties:
      backoff:
        description: Backoff is a backoff strategy
        $ref: '#/definitions/Backoff'
      expression:
        description: Expression is a condition expression for when a node will be retried. If it evaluates to false, the node will not be retried and the retry strategy will be ignored
        type: string
      limit:
        description: Limit is the maximum number of retry attempts when retrying a container. It does not include the original container; the maximum number of total attempts will be `limit + 1`.
        type: integer
        format: uint32
      retryPolicy:
        description: RetryPolicy is a policy of NodePhase statuses that will be retried
        $ref: '#/definitions/RetryPolicy'

  Backoff:
    description: Backoff is a backoff strategy to use within retryStrategy
    type: object
    properties:
      duration:
        description: Duration is the amount to back off. Default unit is seconds, but could also be a duration (e.g. "2m", "1h")
        type: string
      factor:
        description: Factor is a factor to multiply the base duration after each failed retry
        type: integer
        format: uint32
      maxDuration:
        description: MaxDuration is the maximum amount of time allowed for the backoff strategy
        type: string

  RetryPolicy:
    description: RetryPolicy is a policy of node statuses that will be retried
    type: string
    enum:
      # Retry always
      - Always
      # Retry task failures
      - OnFailure
      # Retry task errors
      - OnError
      # Retry task transient errors
      - OnTransientError

paths:
  /.stats:
    get:
      description: Fetch libtiledb stat
      tags:
        - stats
      operationId: getTiledbStats
      responses:
        200:
          description: stats
          schema:
            type: object
            properties:
              stats:
                description: string of stats from tiledb
                type: string
                example: "123"
          examples:
            application/json:
              stats: "123"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays:
    parameters:
      - name: public_share
        in: query
        type: string
        description: Public share values can be one of exclude, only
    get:
      description: get all array metadata user has access to
      tags:
        - array
      operationId: getAllArrayMetadata
      responses:
        200:
          description: array metadata for all arrays user has access to
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/ArrayInfo"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
    get:
      description: get metadata on all arrays in a namespace
      tags:
        - array
      operationId: getArraysInNamespace
      responses:
        200:
          description: array metadata for all arrays in a namespace
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/ArrayInfo"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /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
    delete:
      description: delete a array
      tags:
        - array
      operationId: deleteArray
      responses:
        204:
          description: delete array successful
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    get:
      description: get an ArraySchema using a url encoded uri
      produces:
        - application/json
        - application/capnp
      consumes:
        - application/json
        - application/capnp
      tags:
        - array
      operationId: getArray
      responses:
        200:
          description: get ArraySchema
          schema:
            $ref: "#/definitions/ArraySchema"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: create a array schema at a specified URI registered to a group/project
      tags:
        - array
      operationId: createArray
      parameters:
        - name: ArraySchema
          in: body
          description: ArraySchema being created
          schema:
            $ref: "#/definitions/ArraySchema"
          required: true
        - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
          in: header
          description: Optional registered access credentials to use for creation
          type: string
          required: false
      responses:
        204:
          description: schema created successfully
        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
        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 do not contain an array task UUID
    get:
      description: get array activity logs
      tags:
        - array
      operationId: arrayActivityLog
      responses:
        200:
          description: log of array activity
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/ArrayActivityLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/activity/{id}:
    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: id
        in: path
        description: ID of the activity
        type: string
        required: true
    get:
      description: get activity log by ID
      tags:
        - array
      operationId: getActivityLogById
      responses:
        200:
          description: array activity
          schema:
            $ref: "#/definitions/ArrayActivityLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/deregister:
    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
    delete:
      description: deregister a array
      tags:
        - array
      operationId: deregisterArray
      responses:
        204:
          description: deregistered array successful
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/array_metadata:
    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
    get:
      description: get metadata on an array
      tags:
        - array
      produces:
        - application/json
        - application/capnp
      consumes:
        - application/json
        - application/capnp
      operationId: getArrayMetadataCapnp
      responses:
        200:
          description: array metadata for an array
          schema:
            $ref: "#/definitions/ArrayMetadata"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: update metadata on an array
      tags:
        - array
      produces:
        - application/json
        - application/capnp
      consumes:
        - application/json
        - application/capnp
      operationId: updateArrayMetadataCapnp
      parameters:
        - name: arrayMetadataEntries
          in: body
          description: List of metadata entries
          schema:
            $ref: "#/definitions/ArrayMetadata"
          required: true
      responses:
        200:
          description: array metadata updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/fragment_info:
    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: fetch an array's fragment info
      tags:
        - array
      operationId: fragmentInfo
      parameters:
        - name: fragmentInfoRequest
          in: body
          description: ArraySchema being created
          schema:
            $ref: "#/definitions/FragmentInfoRequest"
          required: true
      responses:
        200:
          description: fragment info
          schema:
            $ref: "#/definitions/FragmentInfo"
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/metadata:
    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
    get:
      description: get metadata on an array
      tags:
        - array
      operationId: getArrayMetadata
      responses:
        200:
          description: array metadata for an array
          schema:
            $ref: "#/definitions/ArrayInfo"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: update metadata on an array
      tags:
        - array
      operationId: updateArrayMetadata
      parameters:
        - name: array_metadata
          in: body
          description: array metadata to update
          schema:
            $ref: "#/definitions/ArrayInfoUpdate"
          required: true
      responses:
        204:
          description: array metadata updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/fragment_end_timestamp:
    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: end_timestamp
        in: query
        description: "Milliseconds since Unix epoch"
        type: integer
        format: uint64
        required: false
    get:
      description: Get fragment end_timestamp on an array, will search for the closest end_timestamp to the timestamp asked
      tags:
        - array
      operationId: getFragmentEndTimestamp
      responses:
        200:
          description: fragment end_timestamp on an array
          schema:
            description: "Milliseconds since Unix epoch, end_timestamp of selected fragment or latest timestamp if input timestamp is omitted"
            type: integer
            format: uint64
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/register:
    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
    post:
      description: register an array at a specified URI registered to the given namespace
      tags:
        - array
      operationId: registerArray
      parameters:
        - name: array_metadata
          in: body
          description: metadata associated with array
          schema:
            $ref: "#/definitions/ArrayInfoUpdate"
          required: true
      responses:
        200:
          description: array registered successfully
          schema:
            $ref: "#/definitions/ArrayInfo"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/consolidate:
    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
    post:
      description: consolidate an array at a specified URI
      tags:
        - array
      operationId: consolidateArray
      parameters:
        - name: consolidate_request
          in: body
          description: Consolidate Request
          schema:
            $ref: "#/definitions/ArrayConsolidationRequest"
          required: true
      responses:
        204:
          description: array consolidated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/vacuum:
    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
    post:
      description: vacuum an array at a specified URI
      tags:
        - array
      operationId: vacuumArray
      parameters:
        - name: vaccum_request
          in: body
          description: Vaccum Request
          schema:
            $ref: "#/definitions/ArrayVacuumRequest"
          required: true
      responses:
        204:
          description: array vacuumed successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/share:
    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
    get:
      description: Get all sharing details of the array
      tags:
        - array
      operationId: getArraySharingPolicies
      responses:
        200:
          description: List of all specific sharing policies
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/ArraySharing"
        404:
          description: Array does not exist or user does not have permissions to view array-sharing policies
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Share an array with a user
      tags:
        - array
      operationId: shareArray
      parameters:
        - name: array_sharing
          in: body
          description: Namespace and list of permissions to share with. An empty list of permissions will remove the namespace; if permissions already exist they will be deleted then new ones added. In the event of a failure, the new policies will be rolled back to prevent partial policies, and it's likely the array will not be shared with the namespace at all.
          schema:
            $ref: "#/definitions/ArraySharing"
          required: true
      responses:
        204:
          description: Array shared successfully
        404:
          description: Array does not exist or user does not have permissions to share array
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/non_empty_domain:
    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
      - name: X-Payer
        in: header
        description: Name of organization or user who should be charged for this request
        type: string
    get:
      description: get the non empty domain of an array
      tags:
        - array
      operationId: getArrayNonEmptyDomain
      responses:
        200:
          description: get the non empty domain of an array
          schema:
            $ref: "#/definitions/NonEmptyDomain"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/max_buffer_sizes:
    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: subarray
        in: query
        description: CSV string of subarray to get max buffer sizes for
        type: string
        required: true
      - 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
    get:
      description: get the max buffer sizes of an array for a subarray
      tags:
        - array
      operationId: getArrayMaxBufferSizes
      responses:
        200:
          description: get the max buffer sizes of an array for a subarray
          schema:
            $ref: "#/definitions/MaxBufferSizes"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/udf/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: X-Payer
        in: header
        description: Name of organization or user who should be charged for this request
        type: string
      - name: Accept-Encoding
        in: header
        description: Encoding to use
        type: string
      - name: v2
        in: query
        description: flag to indicate if v2 array UDFs should be used, currently in beta testing. Setting any value will enable v2 array UDFs.
        type: string
        required: false

    post:
      description: send a UDF to run against a specified array/URI registered to a group/project
      tags:
        - udf
      operationId: submitUDF
      produces:
        - application/octet-stream
      consumes:
        - application/json
      parameters:
        - name: udf
          in: body
          description: UDF to run
          schema:
            $ref: "#/definitions/MultiArrayUDF"
          required: true
      responses:
        200:
          description: UDF completed and the UDF-type specific result is returned
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed request
          schema:
            type: string
            format: binary
        502:
          description: Bad Gateway
        default:
          description: error response
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just request if task was started
          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
    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:
            $ref: "#/definitions/Query"
        204:
          description: query completed successfully with no return
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/query/submit_query_json:
    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
      - name: X-Payer
        in: header
        description: Name of organization or user who should be charged for this request
        type: string
    post:
      description: send a query to run against a specified array/URI registered to a group/project, returns JSON results
      tags:
        - query
      produces:
        - application/json
      consumes:
        - application/json
      operationId: submitQueryJson
      parameters:
        - name: queryJson
          in: body
          description: query to run
          schema:
            $ref: "#/definitions/QueryJson"
          required: true
      responses:
        200:
          description: query completed and results are returned in JSON format
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed query
          schema:
            type: object
          examples:
            application/json:
              data: '{"a1":[0,1,2,3,0,1,2,3]}'

        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/query/get_file:
    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
      - name: X-Payer
        in: header
        description: Name of organization or user who should be charged for this request
        type: string
    get:
      description: send a query to run against a specified array/URI registered to a group/project, returns file bytes
      tags:
        - query
      produces:
        - application/x-ipynb+json
      operationId: getFile
      responses:
        200:
          description: query completed and result bytes are returned
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed query
          schema:
            type: string
            format: binary
          examples:
            application/x-ipynb+json:
              data: "abcd"

        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/query/finalize:
    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
    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: finalizeQuery
      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:
            $ref: "#/definitions/Query"
        204:
          description: query completed successfully with no return
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/query/est_result_sizes:
    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
    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: getEstResultSizes
      parameters:
        - name: query
          in: body
          description: query to run
          schema:
            $ref: "#/definitions/Query"
          required: true
      responses:
        200:
          description: query est result size computed and results are returned in query object
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just computed query result size
          schema:
            $ref: "#/definitions/Query"
        204:
          description: query completed successfully with no return
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/{namespace}/{array}/sample:
    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: samples
        in: query
        description: Number of sample results to return
        default: 5
        type: number
        format: uint8
    get:
      description: get an sample set of data from the array
      tags:
        - array
      operationId: getArraySampleData
      responses:
        200:
          description: get array sample data
          schema:
            $ref: "#/definitions/ArraySample"
          examples:
            application/json:
              dim1:
                - 1
                - 2
                - 3
                - 1
                - 2
              dim2:
                - 1
                - 1
                - 1
                - 2
                - 2
              attribute1:
                - 1
                - 2
                - 3
                - 4
                - 5
              attribute2:
                - "test1"
                - "test2"
                - "test3"
                - "test4"
                - "test5"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              message: "Error try again"
              code: 1

  /arrays/{namespace}/{array}/metadata_json:
    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: length
        in: query
        description: (optional) limit character length of returned values
        type: integer
        required: false
      - name: end_timestamp
        in: query
        description: "Milliseconds since Unix epoch, metadata will use open_at functionality to open array at the specific timestamp"
        type: integer
        format: uint64
        required: false
    get:
      description: get metadata from the array in JSON format
      tags:
        - array
      operationId: getArrayMetaDataJson
      responses:
        200:
          description: get array metadata
          schema:
            $ref: "#/definitions/ArrayMetadataJson"
          examples:
            application/json:
              key1: 25
              key2:
                - 25
                - 26
                - 27
                - 28
              key3: 25.1
              key4:
                - 25.1
                - 26.2
                - 27.3
                - 28.4
              key5: "This is TileDB array metadata"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              message: "Error try again"
              code: 1

  /arrays/{namespace}/{array}/non_empty_domain_json:
    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
    get:
      description: get non-empty domain from the array in json format
      tags:
        - array
      operationId: getArrayNonEmptyDomainJson
      responses:
        200:
          description: get array non-empty domaim
          schema:
            $ref: "#/definitions/NonEmptyDomainJson"
          examples:
            application/json:
              dim1:
                - 1
                - 20
              dim2:
                - a
                - c
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              message: "Error try again"
              code: 1

  /arrays/{namespace}/{array}/end_timestamps:
    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: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: retrieve a list of timestamps from the array fragment info listing in milliseconds, paginated
      tags:
        - array
      produces:
        - application/json
      responses:
        200:
          description: list of timestamps in milliseconds, paginated
          schema:
            $ref: "#/definitions/ArrayEndTimestampData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/last_accessed:
    get:
      tags:
        - array
      operationId: getLastAccessedArrays
      responses:
        200:
          description: gets last accessed arrays
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/LastAccessedArray"
          examples:
            application/json:
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              message: "Error try again"
              code: 1

  /user:
    get:
      tags:
        - user
      description: get a user
      operationId: getUser
      responses:
        200:
          description: user details
          schema:
            $ref: "#/definitions/User"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      security: []
      tags:
        - user
      description: create a user
      operationId: createUser
      parameters:
        - name: user
          in: body
          description: user to create
          schema:
            $ref: "#/definitions/User"
          required: true
      responses:
        204:
          description: user created successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /user/password_reset:
    post:
      tags:
        - user
      description: reset user password
      operationId: resetUserPassword
      parameters:
        - name: user
          in: body
          description: password to update for user requesting update
          schema:
            description: Password to update
            type: object
            properties:
              password:
                type: string
                minLength: 8
                description: password
                example: "password"
          required: true
      responses:
        204:
          description: User password updated successfully
        404:
          description: User not found
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /user/confirm_email:
    post:
      tags:
        - user
      description: confirm user email
      operationId: confirmEmail
      responses:
        204:
          description: User email confirmed successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /users/{username}:
    parameters:
      - name: username
        in: path
        description: username or ID
        required: true
        type: string
    get:
      tags:
        - user
      description: get a user
      operationId: getUserWithUsername
      responses:
        200:
          description: user details
          schema:
            $ref: "#/definitions/User"
        404:
          description: User does not exist
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - user
      description: delete a user
      operationId: deleteUser
      responses:
        204:
          description: user deleted
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      tags:
        - user
      description: update a user
      operationId: updateUser
      parameters:
        - name: user
          in: body
          description: user details to update
          schema:
            $ref: "#/definitions/User"
          required: true
      responses:
        204:
          description: user updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /credentials/{namespace}/aws:
    parameters:
      - name: namespace
        in: path
        description: namespace
        required: true
        type: string
    get:
      tags:
        - user
        - organization
      description: Check if aws keys are set
      operationId: checkAWSAccessCredentials
      responses:
        200:
          description: AWS keys are set
          schema:
            type: array
            items:
              $ref: "#/definitions/AWSAccessCredentials"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - user
        - organization
      description: Add aws keys
      operationId: addAWSAccessCredentials
      parameters:
        - name: awsAccessCredentials
          in: body
          description: aws access credentials to store for a namespace
          schema:
            $ref: "#/definitions/AWSAccessCredentials"
          required: true
      responses:
        204:
          description: AWS keys added successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /credentials/{namespace}/aws/{name}:
    parameters:
      - name: namespace
        in: path
        description: namespace
        required: true
        type: string
      - name: name
        in: path
        description: name
        required: true
        type: string
    get:
      tags:
        - user
        - organization
      description: Check if aws keys are set by name
      operationId: checkAWSAccessCredentialsByName
      responses:
        200:
          description: AWS keys are set
          schema:
            $ref: "#/definitions/AWSAccessCredentials"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      tags:
        - user
        - organization
      description: Update aws keys or associated buckets. This will update the key associations for each array in the namespace
      operationId: updateAWSAccessCredentials
      parameters:
        - name: awsAccessCredentials
          in: body
          description: aws credentials to update
          schema:
            $ref: "#/definitions/AWSAccessCredentials"
          required: true
      responses:
        204:
          description: AWS keys updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - user
        - organization
      description: delete a AWS Access credentials in a namespace. This will likely cause arrays to become unreachable
      operationId: deleteAWSAccessCredentials
      responses:
        204:
          description: AWS credentials deleted
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organization:
    post:
      tags:
        - organization
      description: create a organization, the user creating will be listed as owner
      operationId: createOrganization
      parameters:
        - name: organization
          in: body
          description: organization to create
          schema:
            $ref: "#/definitions/Organization"
          required: true
      responses:
        204:
          description: organization created successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organizations:
    get:
      tags:
        - organization
      description: get all organizations that the user is member of
      operationId: getAllOrganizations
      responses:
        200:
          description: array of organizations the user is member of
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/Organization"
        400:
          description: Error finding organizations
        500:
          description: Request user not found, or has empty context
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organizations/{organization}:
    parameters:
      - name: organization
        in: path
        description: organization name or ID
        required: true
        type: string
    get:
      tags:
        - organization
      description: get a organization
      operationId: getOrganization
      responses:
        200:
          description: organization details
          schema:
            $ref: "#/definitions/Organization"
        404:
          description: Organization does not exist
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - organization
      description: delete a organization
      operationId: deleteOrganization
      responses:
        204:
          description: organization deleted
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      tags:
        - organization
      description: update a organization
      operationId: updateOrganization
      parameters:
        - name: organizationDetails
          in: body
          description: organization details to update
          schema:
            $ref: "#/definitions/Organization"
          required: true
      responses:
        204:
          description: organization updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organizations/{organization}/user:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
    post:
      tags:
        - user
        - organization
      description: add a user to an organization
      operationId: addUserToOrganization
      parameters:
        - name: user
          in: body
          description: user to add
          schema:
            $ref: "#/definitions/OrganizationUser"
          required: true
      responses:
        204:
          description: user added to organization successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organizations/{organization}/{username}:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
      - name: username
        in: path
        description: username to manipulate
        required: true
        type: string
    get:
      tags:
        - user
        - organization
      description: get a user from an organization
      operationId: getOrganizationUser
      responses:
        200:
          description: user from organization
          schema:
            $ref: "#/definitions/OrganizationUser"
        404:
          description: User is not in organization
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - user
        - organization
      description: delete a user from an organization
      operationId: deleteUserFromOrganization
      responses:
        204:
          description: user delete from organization successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      tags:
        - user
        - organization
      description: update a user in an organization
      operationId: updateUserInOrganization
      parameters:
        - name: user
          in: body
          description: user details to update
          schema:
            $ref: "#/definitions/OrganizationUser"
          required: true
      responses:
        204:
          description: user update in organization successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /organizations/{organization}/sso_domain:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
    post:
      tags:
        - organization
      description: >
        Create a new SSO connection that connects this organization to this
        domain.
      operationId: createSSODomain
      parameters:
        - name: config
          in: body
          description: The SSO connection to create.
          schema:
            $ref: '#/definitions/SSODomainConfig'
          required: true
      responses:
        200:
          description: Claim created successfully.
          schema:
            $ref: '#/definitions/SSODomainConfig'
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /organizations/{organization}/sso_domains:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
    get:
      tags:
        - organization
      description: >
        Lists all the SSO connections associated with the given organization.
      operationId: getSSODomains
      responses:
        200:
          description: The SSO domains associated with the org.
          schema:
            $ref: '#/definitions/SSODomainConfigResponse'
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /organizations/{organization}/sso_domains/{uuid}:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
      - name: uuid
        in: path
        description: configuration ID
        required: true
        type: string
    get:
      tags:
        - organization
      description: Gets details about the given SSO domain connection.
      operationId: getSSODomain
      responses:
        200:
          description: The details about this domain connection.
          schema:
            $ref: '#/definitions/SSODomainConfig'
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - organization
      description: Updates the configuration for the given SSO connection.
      parameters:
        - name: config
          in: body
          description: The changes to make to the configuration.
          schema:
            $ref: '#/definitions/SSODomainConfig'
          required: true
      operationId: updateSSODomain
      responses:
        200:
          description: The updated details about the SSO connection.
          schema:
            $ref: '#/definitions/SSODomainConfig'
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - organization
      description: Deletes the configuration for the given SSO connection.
      operationId: deleteSSODomain
      responses:
        204:
          description: Deletion successful.
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /organizations/{organization}/sso_domains/{uuid}/run_check:
    parameters:
      - name: organization
        in: path
        description: organization name
        required: true
        type: string
      - name: uuid
        in: path
        description: configuration ID
        required: true
        type: string
    post:
      tags:
        - organization
      description: >
        Immediately verify ownership of the specified SSO domain ownership
        claim.
      operationId: checkSSODomain
      responses:
        200:
          description: >
            The check executed. Detailed results are available in the response.
          schema:
            $ref: '#/definitions/DomainCheckResult'
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /session:
    parameters:
      - name: remember_me
        in: query
        description: flag to create a token with expiration of 30 days, default is false
        type: string
        required: false
    get:
      tags:
        - user
      description: Get session token for user
      operationId: getSession
      responses:
        200:
          description: Session token
          schema:
            $ref: "#/definitions/Token"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tasks:
    parameters:
      - name: namespace
        in: query
        description: namespace to filter
        type: string
        required: false
      - name: created_by
        in: query
        description: username to filter
        type: string
        required: false
      - name: array
        in: query
        description: name/uri of array that is url-encoded to filter
        type: string
        required: false
      - name: start
        in: query
        description: start time for tasks to filter by
        type: integer
        format: uint64
        required: false
      - name: end
        in: query
        description: end time for tasks to filter by
        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
      - name: type
        in: query
        description: task type, "QUERY", "SQL", "UDF", "GENERIC_UDF"
        required: false
        type: string
      - name: exclude_type
        in: query
        description: task_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        items:
          type: string
      - name: file_type
        in: query
        description: match file_type of task array, more than one can be included
        required: false
        collectionFormat: multi
        type: array
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: exclude file_type of task arrays, more than one can be included
        required: false
        collectionFormat: multi
        type: array
        items:
          type: string
      - name: status
        in: query
        description: Filter to only return these statuses
        type: string
        required: false
      - name: search
        in: query
        description: search string that will look at name, namespace or description fields
        required: false
        type: string
      - name: orderby
        in: query
        description: sort by which field valid values include start_time, name
        required: false
        type: string
    get:
      tags:
        - tasks
      description: Fetch a list of all array tasks a user has access to
      responses:
        200:
          description: Array of all tasks user has access too
          schema:
            $ref: "#/definitions/ArrayTaskData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tasks/sidebar:
    parameters:
      - name: start
        in: query
        description: Fetch tasks created after this time, unix epoch in seconds, default 7 days ago
        type: integer
        format: uint64
      - name: end
        in: query
        description: Fetch tasks created before this time, unix epoch in seconds, default now
        type: integer
        format: uint64
    get:
      tags:
        - array_tasks
      operationId: getArrayTasksSidebar
      responses:
        200:
          description: sidebar metadata for task definitions for all arrays user has access to
          schema:
            $ref: "#/definitions/ArrayTaskBrowserSidebar"

          examples:
            application/json:
              organizations:
                - organization1
                - organization2
                - organization3
              result_count_for_all: 74
              result_count_by_namespace:
                mockuser: 14
                organization1: 6
                organization2: 52
                organization3: 2
        404:
          description: array tasks not found
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
          examples:
            application/json:
              message: "Error try again"
              code: 1

  /task/{id}:
    parameters:
      - name: id
        in: path
        description: task ID to fetch
        type: string
        required: true
    get:
      tags:
        - tasks
      description: Fetch an array task
      responses:
        200:
          description: Array task
          schema:
            $ref: "#/definitions/ArrayTask"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /task/{id}/result:
    parameters:
      - name: id
        in: path
        description: task ID to retrieve stored results
        type: string
        required: true
      - name: Accept-Encoding
        in: header
        description: Encoding to use
        type: string
    get:
      tags:
        - tasks
      description: Retrieve results of an array task
      responses:
        200:
          description: output and format of originating request
          schema:
            type: string
            format: binary/json
          headers:
            Content-Type:
              type: string
              description: format results are delivered in
        202:
          description: task is still executing
        404:
          description: results were not saved, or results have expored
          schema:
            $ref: "#/definitions/Error"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /token:
    post:
      tags:
        - user
      description: Request an authorization token, optionally taken a TokenRequest object to set parameters on the token
      operationId: requestToken
      parameters:
        - name: tokenRequest
          in: body
          description: token request object
          schema:
            $ref: "#/definitions/TokenRequest"
          required: false
      responses:
        200:
          description: token
          schema:
            $ref: "#/definitions/Token"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tokens:
    get:
      tags:
        - user
      description: Fetch a list of user tokens
      responses:
        200:
          description: Array of user created non-session tokens
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/Token"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tokens/session:
    get:
      tags:
        - user
      description: Fetch a list of user session tokens
      responses:
        200:
          description: Array of user created session tokens
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/Token"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tokens/{token}:
    parameters:
      - name: token
        in: path
        description: token name or token itself
        required: true
        type: string
    delete:
      tags:
        - user
      description: revoke an authorization token
      operationId: revokeToken
      responses:
        204:
          description: revokation successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /tokens/scopes:
    get:
      tags:
        - user
      description: retrieves available token scopes for a user
      operationId: getTokenScopes
      responses:
        200:
          description: available token scopes
          schema:
            type: array
            items:
              $ref: "#/definitions/TokenScope"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /sql/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace to run task under is in (an organization name or user's username)
        type: string
        required: true
      - name: Accept-Encoding
        in: header
        description: Encoding to use
        type: string
    post:
      tags:
        - sql
        - tasks
      description: Run a sql query
      operationId: runSQL
      parameters:
        - name: sql
          in: body
          description: sql being submitted
          schema:
            $ref: "#/definitions/SQLParameters"
          required: true
      responses:
        200:
          description: JSON results in array of objects form, if the query returns results
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed query
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
        204:
          description: SQL executed successfully
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed query
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udfs/generic/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: Accept-Encoding
        in: header
        description: Encoding to use
        type: string

    post:
      description: submit a generic UDF in the given namespace
      tags:
        - udf
      operationId: submitGenericUDF
      produces:
        - application/octet-stream
      consumes:
        - application/json
      parameters:
        - name: udf
          in: body
          description: UDF to run
          schema:
            $ref: "#/definitions/GenericUDF"
          required: true
      responses:
        200:
          description: UDF completed and the UDF-type specific result is returned
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed request
          schema:
            type: string
            format: binary
        502:
          description: Bad Gateway
        default:
          description: error response
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just request if task was started
          schema:
            $ref: "#/definitions/Error"

  /udfs/arrays/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: Accept-Encoding
        in: header
        description: Encoding to use
        type: string

    post:
      description: submit a multi-array UDF in the given namespace
      tags:
        - udf
      operationId: submitMultiArrayUDF
      produces:
        - application/octet-stream
      consumes:
        - application/json
      parameters:
        - name: udf
          in: body
          description: UDF to run
          schema:
            $ref: "#/definitions/MultiArrayUDF"
          required: true
      responses:
        200:
          description: UDF completed and the UDF-type specific result is returned
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just completed request
          schema:
            type: string
            format: binary
        502:
          description: Bad Gateway
        default:
          description: error response
          headers:
            X-TILEDB-CLOUD-TASK-ID:
              type: string
              description: Task ID for just request if task was started
          schema:
            $ref: "#/definitions/Error"

  /udf/{namespace}/{name}:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: name
        in: path
        description: name to register UDF under
        type: string
        required: true
    get:
      description: get a specific UDF in the given namespace
      tags:
        - udf
      operationId: getUDFInfo
      responses:
        200:
          description: UDFInfo was retrieved successfully
          schema:
            $ref: "#/definitions/UDFInfo"
        404:
          description: UDF not found
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: register a UDF in the given namespace
      tags:
        - udf
      operationId: registerUDFInfo
      parameters:
        - name: udf
          in: body
          description: UDF to register
          schema:
            $ref: "#/definitions/UDFInfoUpdate"
          required: true
      responses:
        204:
          description: UDF registered successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: update an existing registered UDF in the given namespace
      tags:
        - udf
      operationId: updateUDFInfo
      parameters:
        - name: udf
          in: body
          description: UDF to update
          schema:
            $ref: "#/definitions/UDFInfoUpdate"
          required: true
      responses:
        204:
          description: UDF updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      description: delete a registered UDF -- this will remove all sharing and can not be undone
      tags:
        - udf
      operationId: deleteUDFInfo
      responses:
        204:
          description: UDF deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udf/{namespace}/{name}/share:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: name
        in: path
        description: name of UDFInfo
        type: string
        required: true
    get:
      description: Get all sharing details of the UDF
      tags:
        - udf
      operationId: getUDFInfoSharingPolicies
      responses:
        200:
          description: List of all specific sharing policies
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/UDFSharing"
        404:
          description: UDF does not exist or user does not have permissions to view array-sharing policies
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Share a UDF with a user
      tags:
        - udf
      operationId: shareUDFInfo
      parameters:
        - name: udf_sharing
          in: body
          description: Namespace and list of permissions to share with. An empty list of permissions will remove the namespace; if permissions already exist they will be deleted then new ones added. In the event of a failure, the new policies will be rolled back to prevent partial policies, and it's likely the UDF will not be shared with the namespace at all.
          schema:
            $ref: "#/definitions/UDFSharing"
          required: true
      responses:
        204:
          description: UDF shared successfully
        404:
          description: UDF does not exist or user does not have permissions to share UDF
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udf/{namespace}/{name}/copy:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: name
        in: path
        description: name of UDFInfo
        type: string
        required: true
    post:
      description: Copy a tiledb udf at the specified location
      tags:
        - udf
      operationId: HandleCopyUDF
      parameters:
        - name: UDFCopy
          in: body
          description: Input/Output information to copy a UDF
          schema:
            $ref: "#/definitions/UDFCopy"
          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: end_timestamp
          in: query
          description: "Milliseconds since Unix epoch"
          type: integer
          format: uint64
          required: false
      responses:
        201:
          description: UDF copied
          schema:
            $ref: "#/definitions/UDFCopied"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udf/{namespace}/{array}/end_timestamps:
    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: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: retrieve a list of timestamps from the array fragment info listing in milliseconds, paginated
      tags:
        - udf
      produces:
        - application/json
      responses:
        200:
          description: list of timestamps in milliseconds, paginated
          schema:
            $ref: "#/definitions/ArrayEndTimestampData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/server/{namespace}/status:
    parameters:
      - name: namespace
        in: path
        description: namespace notebook is in (an organization name or user's username)
        type: string
        required: true
    get:
      description: Get status of the notebook server
      tags:
        - notebook
      operationId: getNotebookServerStatus
      responses:
        200:
          description: status of running notebook
          schema:
            $ref: "#/definitions/NotebookStatus"
        202:
          description: Notebook server is pending
        402:
          description: Payment required
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Notebook is not running
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/server/{namespace}:
    parameters:
      - name: namespace
        in: path
        description: namespace notebook is in (an organization name or user's username)
        type: string
        required: true
    delete:
      description: Shutdown a notebook server
      tags:
        - notebook
      operationId: shutdownNotebookServer
      responses:
        204:
          description: Notebook shutdown successfully
        404:
          description: Notebook is not running
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/{array}/rename:
    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 notebook (array) that is url-encoded
        type: string
        required: true
    patch:
      description: update name on a notebok, moving related S3 object to new location
      tags:
        - notebook
      operationId: updateNotebookName
      parameters:
        - name: notebook_metadata
          in: body
          description: notebook (array) metadata to update
          schema:
            $ref: "#/definitions/ArrayInfoUpdate"
          required: true
      responses:
        204:
          description: notebook name updated successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/{array}/copy:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the notebook
      - type: string
        name: array
        in: path
        required: true
        description: The name of the notebook
      - name: NotebookCopy
        in: body
        description: Input/Output information to create a new TileDB file
        schema:
          $ref: "#/definitions/NotebookCopy"
        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: end_timestamp
        in: query
        description: "Milliseconds since Unix epoch, copy will use open_at functionality to copy notebook created at the specific timestamp"
        type: integer
        format: uint64
        required: false
    post:
      description: Copy a tiledb notebook at the specified location
      tags:
        - notebook
      operationId: HandleCopyNotebook
      responses:
        201:
          description: Notebook copied
          schema:
            $ref: "#/definitions/NotebookCopied"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/upload:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the notebook
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
    post:
      description: Upload a notebook at the specified location
      consumes:
        - multipart/form-data
      tags:
        - notebook
      operationId: HandleUploadNotebook
      parameters:
        - in: formData
          name: input_file
          type: file
          required: true
          description: the notebook to upload
        - in: formData
          name: output_uri
          type: string
          description: output location of the TileDB File
        - in: formData
          name: name
          type: string
          description: name to set for registered file
      responses:
        201:
          description: File uploaded
          schema:
            $ref: "#/definitions/FileUploaded"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/{array}/end_timestamps:
    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: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
    get:
      description: retrieve a list of timestamps from the array fragment info listing in milliseconds, paginated
      tags:
        - notebooks
      produces:
        - application/json
      responses:
        200:
          description: list of timestamps in milliseconds, paginated
          schema:
            $ref: "#/definitions/ArrayEndTimestampData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/{namespace}/{array}/prune:
    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: keep_versions
        in: query
        description: "The number of most recents fragment to preserve"
        type: integer
        format: uint64
        required: false
    post:
      description: prune fragments of the notebook
      tags:
        - notebooks
      responses:
        204:
          description: notebook pruned
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations:
    parameters:
      - name: organization
        in: query
        description: name or ID of organization to filter
        type: string
        required: false
      - name: array
        in: query
        description: name/uri of array that is url-encoded to filter
        type: string
        required: false
      - name: group
        in: query
        description: name or ID of group to filter
        type: string
        required: false
      - name: start
        in: query
        description: start time for tasks to filter by
        type: integer
        format: uint64
        required: false
      - name: end
        in: query
        description: end time for tasks to filter by
        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
      - name: type
        in: query
        description: invitation type, "ARRAY_SHARE", "JOIN_ORGANIZATION"
        required: false
        type: string
      - name: status
        in: query
        description: Filter to only return "PENDING", "ACCEPTED"
        type: string
        required: false
      - name: orderby
        in: query
        description: sort by which field valid values include timestamp, array_name, organization_name
        required: false
        type: string
    get:
      tags:
        - invitation
      description: Fetch a list of invitations
      operationId: fetchInvitations
      responses:
        200:
          description: List of invitations and pagination metadata
          schema:
            $ref: "#/definitions/InvitationData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/{invitation}:
    parameters:
      - name: invitation
        in: path
        description: the ID of invitation about to be accepted
        type: string
        required: true
    post:
      tags:
        - invitation
      description: Accepts invitation
      operationId: acceptInvitation
      responses:
        204:
          description: Invitation was accepted successfully
        404:
          description: Could not find invitation identifier
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/{invitation}/{namespace}/{array}/share:
    parameters:
      - name: namespace
        in: path
        description: namespace array is in (an organization name or user's username)
        type: string
        required: true
      - name: invitation
        in: path
        description: the ID of invitation about to be cancelled
        type: string
        required: true
      - name: array
        in: path
        description: name/uri of array that is url-encoded
        type: string
        required: true
    delete:
      description: Cancels array sharing invitation
      tags:
        - invitation
      operationId: cancelShareArrayByInvite
      responses:
        204:
          description: Invitation cancelled successfully
        404:
          description: No invitation was found to cancel
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/group/{invitation}/{namespace}/{group_name}/share:
    parameters:
      - name: namespace
        in: path
        description: namespace group is in (an organization name or user's username)
        type: string
        required: true
      - name: invitation
        in: path
        description: the ID of invitation about to be cancelled
        type: string
        required: true
      - name: group_name
        in: path
        description: name/uuid of group that is url-encoded
        type: string
        required: true
    delete:
      description: Cancels group sharing invitation
      tags:
        - invitation
      operationId: cancelShareGroupByInvite
      responses:
        204:
          description: Invitation cancelled successfully
        404:
          description: No invitation was found to cancel
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/{invitation}/{organization}/join:
    parameters:
      - name: invitation
        in: path
        description: the ID of invitation about to be cancelled
        type: string
        required: true
      - name: organization
        in: path
        description: name or UUID of organization
        type: string
        required: true
    delete:
      description: Cancels join organization invitation
      tags:
        - invitation
      operationId: cancelJoinOrganization
      responses:
        204:
          description: Invitation cancelled successfully
        404:
          description: No invitation was found to cancel
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/{namespace}/{array}/share:
    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
    post:
      tags:
        - invitation
      description: Sends email to multiple recipients with sharing information regarding an array
      operationId: shareArrayByInvite
      parameters:
        - name: email_invite
          in: body
          description: list of email recipients
          schema:
            $ref: "#/definitions/InvitationArrayShareEmail"
          required: true
      responses:
        204:
          description: Email sent successfully to user for email confirmation link
        207:
          description: Only a portion of the invitations succeeded, some failed
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        500:
          description: Could not reach any recipients
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/group/{namespace}/{group}/share:
    parameters:
      - name: namespace
        in: path
        description: namespace group is in (an organization name or user's username)
        type: string
        required: true
      - name: group
        in: path
        description: name/uri of group that is url-encoded
        type: string
        required: true
    post:
      tags:
        - invitation
      description: Sends email to multiple recipients with sharing information regarding a group
      operationId: shareGroupByInvite
      parameters:
        - name: email_invite
          in: body
          description: list of email/namespace recipients
          schema:
            $ref: "#/definitions/InvitationGroupShareEmail"
          required: true
      responses:
        204:
          description: Email sent successfully to user with an email confirmation link
        207:
          description: Only a portion of the invitations succeeded, some failed
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        500:
          description: Could not reach any recipients
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /invitations/{organization}/join:
    parameters:
      - name: organization
        in: path
        description: name or UUID of organization
        type: string
        required: true
    post:
      tags:
        - invitation
      description: Sends email to multiple recipients with joining information regarding an organization
      operationId: joinOrganization
      parameters:
        - name: email_invite
          in: body
          description: list of email recipients
          schema:
            $ref: "#/definitions/InvitationOrganizationJoinEmail"
          required: true
      responses:
        204:
          description: Email sent successfully to user for email confirmation link
        207:
          description: Only a portion of the invitations succeeded, some failed
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        500:
          description: Could not reach any recipients
          schema:
            $ref: "#/definitions/InvitationFailedRecipients"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/shared:
    parameters:
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
      - name: search
        in: query
        description: search string that will look at name, namespace or description fields
        required: false
        type: string
      - name: namespace
        in: query
        description: namespace
        required: false
        type: string
      - name: orderby
        in: query
        description: sort by which field valid values include last_accessed, size, name
        required: false
        type: string
      - name: permissions
        in: query
        description: permissions valid values include read, read_write, write, admin
        required: false
        type: string
      - name: tag
        in: query
        description: tag to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_tag
        in: query
        description: tags to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: shared_to
        in: query
        description: namespaces to filter results of where there arrays were shared to
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a list of all arrays that have been shared with the user
      responses:
        200:
          description: Array of array info that has been shared with the user
          schema:
            $ref: "#/definitions/ArrayBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/shared/sidebar:
    parameters:
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: shared_to
        in: query
        description: namespaces to filter results of where there groups were shared to
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a list of all arrays that have been shared with the user
      responses:
        200:
          description: Array of array info that has been shared with the user
          schema:
            $ref: "#/definitions/ArrayBrowserSidebar"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/public:
    parameters:
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
      - name: search
        in: query
        description: search string that will look at name, namespace or description fields
        required: false
        type: string
      - name: namespace
        in: query
        description: namespace
        required: false
        type: string
      - name: orderby
        in: query
        description: sort by which field valid values include last_accessed, size, name
        required: false
        type: string
      - name: permissions
        in: query
        description: permissions valid values include read, read_write, write, admin
        required: false
        type: string
      - name: tag
        in: query
        description: tag to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_tag
        in: query
        description: tags to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a list of all arrays that have been shared publically
      responses:
        200:
          description: Array of array info that has been shared publically
          schema:
            $ref: "#/definitions/ArrayBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/public/sidebar:
    parameters:
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a sidebar of all arrays that have been shared publically
      responses:
        200:
          description: Array of array info that has been shared publically
          schema:
            $ref: "#/definitions/ArrayBrowserSidebar"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/owned:
    parameters:
      - name: page
        in: query
        description: pagination offset
        type: integer
        required: false
      - name: per_page
        in: query
        description: pagination limit
        type: integer
        required: false
      - name: search
        in: query
        description: search string that will look at name, namespace or description fields
        required: false
        type: string
      - name: namespace
        in: query
        description: namespace
        required: false
        type: string
      - name: orderby
        in: query
        description: sort by which field valid values include last_accessed, size, name
        required: false
        type: string
      - name: permissions
        in: query
        description: permissions valid values include read, read_write, write, admin
        required: false
        type: string
      - name: tag
        in: query
        description: tag to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_tag
        in: query
        description: tags to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a list of all arrays that are owned directly by user or user's organizations
      responses:
        200:
          description: Array of array info that are owned directly by user or user's organizations
          schema:
            $ref: "#/definitions/ArrayBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/browser/owned/sidebar:
    parameters:
      - name: file_type
        in: query
        description: file_type to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: exclude_file_type
        in: query
        description: file_type to exclude matching array in results, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
      - name: file_property
        in: query
        description: file_property key-value pair (comma separated, i.e. key,value) to search for, more than one can be included
        required: false
        type: array
        collectionFormat: multi
        items:
          type: string
    get:
      tags:
        - array
      description: Fetch a sidebar for arrays that are owned directly by user or user's organizations
      responses:
        200:
          description: Array of array info that are owned directly by user or user's organizations
          schema:
            $ref: "#/definitions/ArrayBrowserSidebar"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/favorites:
    get:
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
      tags:
        - favorites
      description: Fetch a page of array favorites of connected user
      operationId: listArrayFavorites
      responses:
        200:
          description: Available array favorites are returned
          schema:
            $ref: "#/definitions/ArrayFavoritesData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/favorites/uuids:
    get:
      tags:
        - favorites
      description: Fetch all favorite array uuids of connected user
      operationId: listArrayFavoritesUUIDs
      responses:
        200:
          description: Available favorites array uuids are returned
          schema:
            type: array
            x-omitempty: false
            items:
              $ref: "#/definitions/ArrayFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /arrays/favorites/{namespace}/{name}:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the array
      - type: string
        name: name
        in: path
        required: true
        description: The name of the array
    get:
      tags:
        - favorites
      description: Fetch array favorite of a specific array
      operationId: getArrayFavorite
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/ArrayFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - favorites
      description: Add a new array favorite
      operationId: addArrayFavorite
      responses:
        204:
          description: Item added to favorites successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - favorites
      description: Delete specific array favorite
      operationId: deleteArrayFavorite
      responses:
        204:
          description: array favorite item deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/favorites:
    get:
      parameters:
        - name: is_dashboard
          in: query
          description: return only dashboards
          type: boolean
          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
      tags:
        - favorites
      description: Fetch a page of notebook favorites of connected user
      operationId: listNotebookFavorites
      responses:
        200:
          description: Available notebook favorites are returned
          schema:
            $ref: "#/definitions/NotebookFavoritesData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/favorites/uuids:
    get:
      tags:
        - favorites
      description: Fetch all favorite notebook uuids of connected user
      operationId: listNotebookFavoritesUUIDs
      responses:
        200:
          description: Available favorites notebook uuids are returned
          schema:
            type: array
            x-omitempty: false
            items:
              $ref: "#/definitions/NotebookFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /notebooks/favorites/{namespace}/{name}:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the notebook
      - type: string
        name: name
        in: path
        required: true
        description: The name of the notebook
    get:
      tags:
        - favorites
      description: Fetch notebook favorite of a specific notebook
      operationId: getNotebookFavorite
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/NotebookFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - favorites
      description: Add a new notebook favorite
      operationId: addNotebookFavorite
      responses:
        204:
          description: Item added to favorites successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - favorites
      description: Delete specific notebook favorite
      operationId: deleteNotebookFavorite
      responses:
        204:
          description: notebook favorite item deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /ml_models/favorites:
    get:
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
      tags:
        - favorites
      description: Fetch a page of ML models favorites of connected user
      operationId: listMLModelFavorites
      responses:
        200:
          description: Available ML models favorites are returned
          schema:
            $ref: "#/definitions/MLModelFavoritesData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /ml_models/favorites/uuids:
    get:
      tags:
        - favorites
      description: Fetch all favorite ML models uuids of connected user
      operationId: listMLModelFavoritesUUIDs
      responses:
        200:
          description: Available favorites ML model uuids are returned
          schema:
            type: array
            x-omitempty: false
            items:
              $ref: "#/definitions/MLModelFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /ml_models/favorites/{namespace}/{name}:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the ML model
      - type: string
        name: name
        in: path
        required: true
        description: The name of the ML model
    get:
      tags:
        - favorites
      description: Fetch ML model favorite of a specific ML model
      operationId: getMLModelFavorite
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MLModelFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - favorites
      description: Add a new ML model favorite
      operationId: addMLModelFavorite
      responses:
        204:
          description: Item added to favorites successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - favorites
      description: Delete specific ML model favorite
      operationId: deleteMLModelFavorite
      responses:
        204:
          description: ML model favorite item deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udfs/favorites:
    get:
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
      tags:
        - favorites
      description: Fetch a page of UDF favorites of connected user
      operationId: listUDFFavorites
      responses:
        200:
          description: Available UDF favorites are returned
          schema:
            $ref: "#/definitions/UDFFavoritesData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udfs/favorites/uuids:
    get:
      tags:
        - favorites
      description: Fetch all favorite UDF uuids of connected user
      operationId: listUDFFavoritesUUIDs
      responses:
        200:
          description: Available favorites UDF uuids are returned
          schema:
            type: array
            x-omitempty: false
            items:
              $ref: "#/definitions/UDFFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /udfs/favorites/{namespace}/{name}:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the UDF
      - type: string
        name: name
        in: path
        required: true
        description: The name of the UDF
    get:
      tags:
        - favorites
      description: Fetch UDF favorite of a specific UDF
      operationId: getUDFFavorite
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/UDFFavorite"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      tags:
        - favorites
      description: Add a new UDF favorite
      operationId: addUDFFavorite
      responses:
        204:
          description: Item added to favorites successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      tags:
        - favorites
      description: Delete specific UDF favorite
      operationId: deleteUDFFavorite
      responses:
        204:
          description: UDF favorite item deleted successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /files/{namespace}:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the file
      - name: FileCreate
        in: body
        description: Input/Output information to create a new TileDB file
        schema:
          $ref: "#/definitions/FileCreate"
        required: true
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
    post:
      description: Create a tiledb file at the specified location
      tags:
        - files
      operationId: HandleCreateFile
      responses:
        201:
          description: File created
          schema:
            $ref: "#/definitions/FileCreated"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /files/{namespace}/upload:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the file
      - name: X-TILEDB-CLOUD-ACCESS-CREDENTIALS-NAME
        in: header
        description: Optional registered access credentials to use for creation
        type: string
        required: false
    post:
      description: Upload a tiledb file at the specified location
      consumes:
        - multipart/form-data
      tags:
        - files
      operationId: HandleUploadFile
      parameters:
        - in: formData
          name: input_file
          type: file
          required: true
          description: the file to upload
        - in: formData
          name: output_uri
          type: string
          description: output location of the TileDB File
        - in: formData
          name: name
          type: string
          description: name to set for registered file
      responses:
        201:
          description: File uploaded
          schema:
            $ref: "#/definitions/FileUploaded"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /files/{namespace}/{file}/export:
    parameters:
      - type: string
        name: namespace
        in: path
        required: true
        description: The namespace of the file
      - type: string
        name: file
        in: path
        required: true
        description: The file identifier
      - name: FileExport
        in: body
        description: Export configuration information
        schema:
          $ref: "#/definitions/FileExport"
        required: true
    post:
      description: Export a TileDB File back to its original file format
      tags:
        - files
      operationId: HandleExportFile
      responses:
        201:
          description: File exported
          schema:
            $ref: "#/definitions/FileExported"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/owned/filters:
    get:
      tags:
        - groups
      description: Fetch data to initialize filters for the groups browser
      parameters:
        - name: namespace
          in: query
          description: namespace
          required: false
          type: string
      responses:
        200:
          description: Filter data
          schema:
            $ref: "#/definitions/GroupBrowserFilterData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/owned:
    get:
      description: Returns one page of owned groups.
      operationId: listOwnedGroups
      tags:
        - groups
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
        - name: group_type
          in: query
          description: filter by a specific group type
          required: false
          type: string
        - name: search
          in: query
          description: search string that will look at name, namespace or description fields
          required: false
          type: string
        - name: namespace
          in: query
          description: namespace
          required: false
          type: string
        - name: orderby
          in: query
          description: sort by which field valid values include last_accessed, size, name
          required: false
          type: string
        - name: permissions
          in: query
          description: permissions valid values include read, read_write, write, admin
          required: false
          type: string
        - name: tag
          in: query
          description: tag to search for, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: exclude_tag
          in: query
          description: tags to exclude matching array in results, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: flat
          in: query
          description: if true, ignores the nesting of groups and searches all of them
          type: boolean
        - name: parent
          in: query
          description: search only the children of the groups with this uuid
          type: string
          required: false
      responses:
        200:
          description: the group contents
          schema:
            $ref: "#/definitions/GroupBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/shared/filters:
    get:
      tags:
        - groups
      description: Fetch data to initialize filters for the groups browser
      parameters:
        - name: namespace
          in: query
          description: namespace
          required: false
          type: string
      responses:
        200:
          description: Filter data
          schema:
            $ref: "#/definitions/GroupBrowserFilterData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/shared:
    get:
      description: Returns one page of shared groups.
      operationId: listSharedGroups
      tags:
        - groups
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
        - name: group_type
          in: query
          description: filter by a specific group type
          required: false
          type: string
        - name: search
          in: query
          description: search string that will look at name, namespace or description fields
          required: false
          type: string
        - name: namespace
          in: query
          description: namespace
          required: false
          type: string
        - name: orderby
          in: query
          description: sort by which field valid values include last_accessed, size, name
          required: false
          type: string
        - name: permissions
          in: query
          description: permissions valid values include read, read_write, write, admin
          required: false
          type: string
        - name: tag
          in: query
          description: tag to search for, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: exclude_tag
          in: query
          description: tags to exclude matching array in results, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: flat
          in: query
          description: if true, ignores the nesting of groups and searches all of them
          type: boolean
        - name: parent
          in: query
          description: search only the children of the groups with this uuid
          type: string
          required: false
        - name: shared_to
          in: query
          description: namespaces to filter results of where there groups were shared to
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
      responses:
        200:
          description: the group contents
          schema:
            $ref: "#/definitions/GroupBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/public/filters:
    get:
      tags:
        - groups
      description: Fetch data to initialize filters for the groups browser
      responses:
        200:
          description: Filter data
          schema:
            $ref: "#/definitions/GroupBrowserFilterData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/browser/public:
    get:
      description: Returns one page of public groups.
      operationId: listPublicGroups
      tags:
        - groups
      parameters:
        - name: page
          in: query
          description: pagination offset
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit
          type: integer
          required: false
        - name: group_type
          in: query
          description: filter by a specific group type
          required: false
          type: string
        - name: search
          in: query
          description: search string that will look at name, namespace or description fields
          required: false
          type: string
        - name: namespace
          in: query
          description: namespace
          required: false
          type: string
        - name: orderby
          in: query
          description: sort by which field valid values include last_accessed, size, name
          required: false
          type: string
        - name: permissions
          in: query
          description: permissions valid values include read, read_write, write, admin
          required: false
          type: string
        - name: tag
          in: query
          description: tag to search for, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: exclude_tag
          in: query
          description: tags to exclude matching array in results, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: flat
          in: query
          description: if true, ignores the nesting of groups and searches all of them
          type: boolean
        - name: parent
          in: query
          description: search only the children of the groups with this uuid
          type: string
          required: false
      responses:
        200:
          description: the group contents
          schema:
            $ref: "#/definitions/GroupBrowserData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/contents/filters:
    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
    get:
      tags:
        - groups
      description: Fetch data to initialize filters for the group contents
      responses:
        200:
          description: Filter data
          schema:
            $ref: "#/definitions/GroupContentsFilterData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/contents:
    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:
      description: Changes the contents of the group by adding/removing members.
      operationId: changeGroupContents
      tags:
        - groups
      parameters:
        - in: body
          name: GroupChanges
          schema:
            $ref: "#/definitions/GroupChanges"
      responses:
        204:
          description: all changes applied successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    get:
      description: Returns the contents of the group
      operationId: getGroupContents
      tags:
        - groups
      parameters:
        - name: page
          in: query
          description: pagination offset for assets
          type: integer
          required: false
        - name: per_page
          in: query
          description: pagination limit for assets
          type: integer
          required: false
        - name: namespace
          in: query
          description: namespace to search for
          required: false
          type: string
        - name: search
          in: query
          description: search string that will look at name, namespace or description fields
          required: false
          type: string
        - name: orderby
          in: query
          description: sort by which field valid values include last_accessed, size, name
          required: false
          type: string
        - name: tag
          in: query
          description: tag to search for, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: exclude_tag
          in: query
          description: tags to exclude matching array in results, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: member_type
          in: query
          description: member type to search for, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
        - name: exclude_member_type
          in: query
          description: member type to exclude matching groups in results, more than one can be included
          required: false
          type: array
          collectionFormat: multi
          items:
            type: string
      responses:
        200:
          description: the group contents
          schema:
            $ref: "#/definitions/GroupContents"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{namespace}/{array}/register:
    parameters:
      - name: namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
      - name: array
        type: string
        in: path
        required: true
        description: The unique name or id of the group
    post:
      description: Registers an existing group in the namespace.
      operationId: registerGroup
      tags:
        - groups
      parameters:
        - in: body
          name: GroupRegister
          schema:
            $ref: "#/definitions/GroupRegister"
      responses:
        204:
          description: group created successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{namespace}/create:
    parameters:
      - name: namespace
        type: string
        in: path
        required: true
        description: The namespace of the group
    post:
      description: Creates a new group in the namespace.
      operationId: createGroup
      tags:
        - groups
      parameters:
        - in: body
          name: GroupCreate
          schema:
            $ref: "#/definitions/GroupCreate"
      responses:
        204:
          description: group created successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /groups/{group_namespace}/{group_name}/share:
    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
    get:
      description: Get all sharing details of the group
      tags:
        - groups
      operationId: getGroupSharingPolicies
      responses:
        200:
          description: List of all specific sharing policies
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/GroupSharing"
        404:
          description: Group does not exist or user does not have permissions to view group-sharing policies
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Share a group with a namespace
      tags:
        - groups
      operationId: shareGroup
      parameters:
        - name: group_sharing_request
          in: body
          description: Namespace and list of permissions to share with. Sharing is recursive, it is applied to all reachable subgroups and arrays of the group. An empty list of permissions will remove the namespace; if permissions already exist they will be deleted then new ones added. In the event of a failure, the new policies will be rolled back to prevent partial policies, and it's likely the group will not be shared with the namespace at all.
          schema:
            $ref: "#/definitions/GroupSharingRequest"
          required: true
      responses:
        204:
          description: Group shared successfully
        404:
          description: Group does not exist or user does not have permissions to share group
        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
    get:
      description: Returns the the group
      operationId: getGroup
      tags:
        - groups
      responses:
        200:
          description: the group metadata
          schema:
            $ref: "#/definitions/GroupInfo"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Changes attributes of the group
      operationId: updateGroup
      tags:
        - groups
      parameters:
        - in: body
          name: GroupUpdate
          schema:
            $ref: "#/definitions/GroupUpdate"
      responses:
        204:
          description: attributes changed successfully
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      description: Deletes the group. The assets are not deleted nor are not relocated to any other 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: Returns the activity of group content
      operationId: getGroupActivity
      tags:
        - groups
      responses:
        200:
          description: Activity logs of group contents along with the pagination metadata
          schema:
            $ref: "#/definitions/GroupActivityResponse"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/log:
    post:
      description: Create a task graph log.
      operationId: createTaskGraphLog
      tags:
        - task_graph_logs
      parameters:
        - name: namespace
          in: path
          description: The namespace that will own this task graph log.
          type: string
          required: true
        - name: log
          in: body
          required: true
          schema:
            $ref: "#/definitions/TaskGraphLog"
      responses:
        201:
          description: >
            The task graph was created. The returned TaskGraphLog will include
            the data the client sent, with the server-defined fields added in.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  # Task graphs: Logs

  /taskgraphs/logs:
    parameters:
      - name: namespace
        in: query
        description: Include logs for this namespace.
        type: string
        required: false
      - name: created_by
        in: query
        description: Include logs from only this user.
        type: string
        required: false
      - name: search
        in: query
        description: search string that will look at name.
        required: false
        type: string
      - name: start_time
        in: query
        description: Include logs created after this time.
        type: string
        format: date-time
        required: false
      - name: end_time
        in: query
        description: Include logs created before this time.
        type: string
        format: date-time
        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: >
        Fetch the task graph logs of a namespace the user has access to. The
        returned entries will include only summary data, and will not include
        information about the individual tasks that were executed. (This
        information is available when requesting an individual task graph log.)

        Entries in the response are ordered from newest to oldest. Pagination
        parameters work as in other API methods; see PaginationMetadata.

      operationId: listTaskGraphLogs
      tags:
        - task_graph_logs
      responses:
        200:
          description: The task graph logs that matched the user's query.
          schema:
            $ref: "#/definitions/TaskGraphLogsData"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/logs/{id}:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph log.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph log entry.
        type: string
        required: true
    get:
      description: >
        Fetch information about a single task graph execution.
      operationId: getTaskGraphLog
      tags:
        - task_graph_logs
      responses:
        200:
          description: Information about the execution of a single task graph.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: >
        Update information about a single task graph execution.
      operationId: updateTaskGraphLog
      tags:
        - task_graph_logs
      parameters:
        - name: log
          in: body
          description: >
            Updates to make to the task graph log. The only manual update
            that a client should need to make to a task graph log is to update
            its completion status to `succeeded`, `failed`, or `cancelled`.
          schema:
            $ref: "#/definitions/TaskGraphLog"
          required: true
      responses:
        204:
          description: Log entry updated successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/logs/{id}/report_client_node:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph log.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph log entry.
        type: string
        required: true
    post:
      operationId: reportClientNode
      tags:
        - task_graph_logs
      parameters:
        - name: report
          in: body
          description: The node status to report.
          required: true
          schema:
            $ref: "#/definitions/TaskGraphClientNodeStatus"
      responses:
        204:
          description: Status reported successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/executions/{id}/resubmit:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph execution.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph execution (TaskGraphLog).
        type: string
        required: true
    post:
      description:  Resubmits a task graph in the given namespace using the associated execution id.
      operationId: resubmitTaskGraphExecution
      tags:
        - task_graph_logs
      responses:
        202:
          description: Information about the task graph execution.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /taskgraphs/{namespace}/executions/{id}/retry:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph execution.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph execution (TaskGraphLog).
        type: string
        required: true
    post:
      description: Retries failed tasks of a task graph in the given namespace using the associated execution id.
      operationId: retryTaskGraphExecution
      tags:
        - task_graph_logs
      responses:
        202:
          description: Information about the task graph execution.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  /taskgraphs/{namespace}/executions/{id}/stop:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph execution.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph execution (TaskGraphLog).
        type: string
        required: true
    post:
      description:  Stops a task graph execution in the given namespace using the associated associated execution id.
      operationId: stopTaskGraphExecution
      tags:
        - task_graph_logs
      responses:
        202:
          description: Information about the task graph execution.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: '#/definitions/Error'

  # Task graphs
  /taskgraphs/{namespace}/graphs:
    get:
      description: >
        Fetch the task graphs of a namespace the user has access to. The
        returned entries will include only summary data, and will not include
        information about the individual tasks that were executed. (This
        information is available when requesting an individual task graph log.)

        Entries in the response are ordered from newest to oldest. Pagination
        parameters work as in other API methods; see PaginationMetadata.
      operationId: listTaskGraphs
      parameters:
        - name: namespace
          in: path
          description: Namespace for graphs
          type: string
          required: true
      tags:
        - task_graphs
      responses:
        200:
          description: The task graphs that matched the user's query.
          schema:
            $ref: "#/definitions/TaskGraphs"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: >
        Create a single task graph for execution.
      operationId: createTaskGraph
      tags:
        - task_graphs
      parameters:
        - name: namespace
          in: path
          description: Include graphs for this namespace.
          type: string
          required: true
        - name: graph
          in: body
          description: Create the task graph.
          schema:
            $ref: "#/definitions/TaskGraph"
          required: true
      responses:
        201:
          description: Task graph created successfully.
          schema:
            $ref: "#/definitions/TaskGraph"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/graphs/{id}:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph entry.
        type: string
        required: true
    get:
      description: >
        Fetch information about a single task graph.
      operationId: getTaskGraph
      tags:
        - task_graphs
      responses:
        200:
          description: Information about the single task graph.
          schema:
            $ref: "#/definitions/TaskGraph"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: >
        Update information about a single task graph execution.
      operationId: updateTaskGraph
      tags:
        - task_graphs
      parameters:
        - name: graph
          in: body
          description: Updates to make to the task graph.
          schema:
            $ref: "#/definitions/TaskGraph"
          required: true
      responses:
        204:
          description: Task graph created successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/graphs/{id}/submit:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this task graph.
        type: string
        required: true
      - name: id
        in: path
        description: The UUID of the task graph entry.
        type: string
        required: true
    post:
      description: >
       Submit a single task graph for execution.
      operationId: submitTaskGraph
      tags:
        - task_graphs
        - task_graph_logs
      responses:
        202:
          description: Information about the execution of a single task graph.
          schema:
            $ref: "#/definitions/TaskGraphLog"
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  # Task graphs: Registration

  /taskgraphs/{namespace}/registered/{name}:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns this registered UDF.
        type: string
        required: true
      - name: name
        in: path
        description: The name of the registered task graph.
        type: string
        required: true
    get:
      description: >
        Fetch the contents of this registered task graph.
      operationId: getRegisteredTaskGraph
      tags:
        - registered_task_graphs
      responses:
        200:
          description: The contents of the registered task graph.
          schema:
            $ref: '#/definitions/RegisteredTaskGraph'
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    post:
      description: >
        Register a task graph in the given namespace, with the given name.
      operationId: registerRegisteredTaskGraph
      tags:
        - registered_task_graphs
      parameters:
        - name: graph
          in: body
          description: Task graph to register.
          schema:
            $ref: "#/definitions/RegisteredTaskGraph"
      responses:
        204:
          description: Task graph registered successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: >
        Update the contents of an existing registered task graph.
      operationId: updateRegisteredTaskGraph
      tags:
        - registered_task_graphs
      parameters:
        - name: graph
          in: body
          description: The new contents of the task graph.
          schema:
            $ref: "#/definitions/RegisteredTaskGraph"
      responses:
        204:
          description: Task graph updated successfully.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    delete:
      description: >
        Delete the given registered task graph.
      operationId: deleteRegisteredTaskGraph
      tags:
        - registered_task_graphs
      responses:
        204:
          description: Task graph successfully deleted.
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"

  /taskgraphs/{namespace}/registered/{name}/share:
    parameters:
      - name: namespace
        in: path
        description: The namespace that owns the registered task graph.
        type: string
        required: true
      - name: name
        in: path
        description: The name of the task graph.
        type: string
        required: true
    get:
      description: Get sharing policies for the task graph.
      tags:
        - registered_task_graphs
      operationId: getRegisteredTaskGraphSharingPolicies
      responses:
        200:
          description: List of all specific sharing policies
          schema:
            type: array
            x-omitempty: true
            items:
              $ref: "#/definitions/TaskGraphSharing"
        404:
          description: >
            The task graph does not exist (or the user does not have permission
            to view policies)
          schema:
            $ref: '#/definitions/Error'
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"
    patch:
      description: Share a task graph.
      tags:
        - registered_task_graphs
      operationId: shareRegisteredTaskGraph
      parameters:
        - name: task_graph_sharing
          in: body
          description: >
            Namespace and list of permissions to share with.
            An empty list of permissions will remove the namespace;
            if permissions already exist they will be deleted then
            new ones added. In the event of a failure, the new policies
            will be rolled back to prevent partial policies, and it's likely
            the UDF will not be shared with the namespace at all.
          schema:
            $ref: "#/definitions/TaskGraphSharing"
          required: true
      responses:
        204:
          description: UDF shared successfully
        404:
          description: UDF does not exist or user does not have permissions to share UDF
          schema:
            $ref: '#/definitions/Error'
        502:
          description: Bad Gateway
        default:
          description: error response
          schema:
            $ref: "#/definitions/Error"