openapi: 3.1.0
info:
  version: 1.3.1
  title: Imago API for Developers
  description: >
    ## Imago's integration and embedding API


    Imago extracts value from geoscientific imagery. It consolidates, transforms
    and delivers imagery into those applications most relevant to each image
    type. This external integration is achieved via the Imago Developer APIs.


    There are two ways to interface with Imago:


    * Integration via a Web RESTFul API, or

    * [Linking to images or web views inside your
    applications.](#linking-light-table)


    ## Workspaces, Datasets and other Data Structures


    Imago has a hierarchy to catalogue stored images. This hierarchy is:


    |Level        | Description |    Example  |

    |-------------|-------------|-------------|

    |Workspaces | Groups multiple datasets together. | Chile Exploration|

    |Datasets | A dataset is a group of related collections.| Pampa Maria, Mia
    Culpa|

    |Collections | A collection manages all images for a single location, object
    or activity e.g. it could be a drillhole, land tenement, drilling rig,
    sampling station, etc... It usually has a geographical location associated
    with it, however this is optional.    | DH001, DH002, LH101|

    |Imagery Types |Describes a logical grouping of imagery within the
    collection. | Core Trays, Hand Samples, Drone Flyover, Maps |

    |Imagery | An imagery is a group of images of the same imagery type on a
    collection. It usually has an additional geographic reference that
    identifies its position within the collection, however this is optional e.g.
    from/to interval, sample location in tenement, equipment location. | 0m -
    3.5m, 3.5m - 7.8m |

    |Image Types | Each image is stored against an imagery and identified by its
    image type. | Wet, Dry (for core trays) Shift Start, Shift End (for drill
    rigs) |


    In Imago, every piece of data (i.e. workspaces, imagery, etc...) is
    identified using named keys (e.g. workspace name, dataset name, etc...).


    ## User's Context


    A user's context is a description of the workspaces, datasets, imagery types
    and image types that are accessible to them. This description provides named
    keys that are used through the API to reference different information. 


    ## Integration API


    The integration API is a standard Web Service RESTFul API. 


    An application must sign into Imago and receive an authorisation token
    before further API calls are permitted. The authorisation token represents a
    session and expires after a set period of time.


    Each API call must include the authorisation token using the header
    "imago-api-token" on the HTTP request.


    <h1 id="linking-light-table">Linking to the Light Table</h1>


    An application can link to imagery and display it using the light table on
    the Imago web site e.g.


    https://imago.seequent.com/api/display?de=AA222&ds=Core%20Boxes&im=Dry&dp=35


    This example searches for a collection called **AA222** and finds all images
    of image type **Dry** in the **Core Boxes** imagery type. These images are
    then displayed on the light table. The light table is adjusted to show
    imagery at a depth of **35m**.


    Alternatively, it can search by collection only. The light table will show
    the first imagery and image types listed for the matching collection.


    https://imago.seequent.com/api/display?de=AA222&dp=35


    ## Constructing the URL


    The URL must use the address: `https://imago.seequent.com/api/display?query`


    The following query parameters control how to search for images:


    Parameter|Description|Required|

    ---------|-----------|--------|
     pj | Workspace name| optional|
     da | Dataset name| optional|
     de | Collection name|mandatory|
     ds | Imagery type name|optional|
     im | Image type name|optional|
     dp | Display at this depth|optional|
     ig | Display at image with this name|optional|

    If the workspace or dataset parameters are provided then they will restrict
    the search for the collection. Without these parameters, the light table
    will search across all workspaces/datasets until it finds a collection that
    matches. If no imagery type or image type is specified then it will display
    the first imagery/image type listed in the collection's dataset.


    Unlike the integration API, no GUID identifiers are used to search for data.
    Instead, the linking option uses data names. This can lead to conflicts if
    naming is not unique within the workspace or dataset. If more than one
    collection matches the query name then they are all added to the light
    table.


    All data names are case sensitive.



    # Support


    ## Service Account Creation


    A service account is a special account used by an application or a service
    for machine-to-machine communication, such as for APIs. These accounts are
    not linked to a specific user but are used by system processes.


    To access our API, a service account requires a unique username and
    password. This ensures secure and authorised access to our API resources.


    For service account creation, which includes obtaining a unique username and
    password, please contact our Support Team at
    https://my.seequent.com/support/request.
servers:
  - url: https://imago.api.seequent.com/integrate/2
    description: ""
tags:
  - name: Session
    description: ""
  - name: User Context
    description: ""
  - name: Collection
    description: ""
  - name: Imagery
    description: ""
paths:
  /session:
    post:
      tags:
        - Session
      summary: Sign into Imago
      description: Signs into Imago using a username and password and creates an
        active session.
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/postSessionSuccessSchema"
              example:
                uid: 23c6727c-a5a6-484b-ac33-9812b9878f0a
                apiToken: b4ecb7d7-b8bb-460f-9506-134df358f471
        "401":
          description: Not authorised to sign in with the supplied credentials.
        "404":
          description: Internal error occurred during the request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/postSessionBodySchema"
            example:
              username: my_user_name
              password: my_password
    get:
      tags:
        - Session
      summary: Check if still signed in
      description: Checks if a user is still signed into imago and has an active session.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getSessionSuccessSchema"
              example:
                uid: 23c6727c-a5a6-484b-ac33-9812b9878f0a
        "401":
          description: Not authorised to sign in with the supplied credentials.
        "404":
          description: Internal error occurred during the request.
    delete:
      tags:
        - Session
      summary: Sign out of Imago
      description: Sign a user out of imago and ends the current active session.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
        "401":
          description: Not authorised to sign in with the supplied credentials.
        "404":
          description: Internal error occurred during the request.
  /context:
    get:
      tags:
        - User Context
      summary: Get the user
      description: The user context describes the list of workspaces and other
        information accessible by that user. Each workspace is described by its
        dataset and its imagery types definitions.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getUserContextSuccessSchema"
              example:
                workspaces:
                  - id: a27b51bf-b918-4fb4-a28f-4f089bf646a8
                    name: Firefly Resource Development
                    readonly: false
                    datasets:
                      - id: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                        name: Drilling Chips
                        lengthUnits: metres
                        imageryTypes:
                          - id: 6a69bf8e-c03c-4ed2-8a62-d6feac838f12
                            name: Chips
                            contentType: chiptray
                            geometryType: trace
                            coordinateType: geographic
                            imageTypes:
                              - id: 8b0634bf-1136-4b5e-a247-c219e77fb92e
                                name: Dry
                                dataType: image
                                baseImageTypeName: null
                                sourceType: O
                              - id: f16c5dbe-f455-4076-8358-ffda8f538814
                                name: Wet
                                dataType: image
                                baseImageTypeName: null
                                sourceType: O
                            attributeDefinitions:
                              - name: Core Tray Box Numbers
                                attributeTypes:
                                  - name: RowNumber
                                    dataType: number
                                  - name: StartBox
                                    dataType: number
                                  - name: EndBox
                                    dataType: number
                              - name: Assays
                                attributeTypes:
                                  - name: ag_ppm
                                    dataType: number
                                  - name: cu_ppm
                                    dataType: number
                                  - name: mo_ppm
                                    dataType: number
                            labelDefinitions:
                              - name: Status
                                labelTypes:
                                  - name: Planned
                                  - name: In Progress
                                  - name: Done
                            featureDefinitions:
                              - name: Linearization
                                featureTypes:
                                  - name: boundary
                                    colour: "#F00"
                                    shapeType: quadrilateral
                                  - name: row
                                    colour: "#ffff00"
                                    shapeType: quadrilateral
                            enableAutoCrop: false
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
  /collection:
    get:
      tags:
        - Collection
      summary: Search for collections
      description: Searches for a list of matching collections. Each collection is
        described by its name and dataset id. Either use the datasetName and
        workspaceName params to filter by dataset/workspace name, or use
        datasetId to search in a specific dataset.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
        - name: name
          in: query
          description: Search pattern to match collection names. If no search pattern is
            supplied then all collections are returned for the dataset.
          required: false
          schema:
            type: string
        - name: datasetId
          in: query
          description: Only returns collections within this dataset.
          required: false
          schema:
            type: string
        - name: match
          in: query
          description: "Determines how the search pattern matches the collection name.
            Wildcards '*' can be used with the 'like' match.<br><br>Default
            value: 'equals'.<br><br>Allowed values: 'equals', 'startswith',
            'endswith', 'includes', 'like'."
          required: false
          schema:
            type: string
        - name: datasetName
          in: query
          description: Search pattern to match dataset name. Only collections within
            matching dataset names are returned.
          required: false
          schema:
            type: string
        - name: workspaceName
          in: query
          description: Search pattern to match workspace name. Only collections within
            matching workspace names are returned.
          required: false
          schema:
            type: string
        - name: offset
          in: query
          description: Return collections starting at this offset.
          required: false
          schema:
            type: number
        - name: limit
          in: query
          description: Limit how many collections are returned.
          required: false
          schema:
            type: number
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/getCollectionSuccessSchema"
              example:
                collections:
                  - id: 054bf4c2-84cc-4d30-b4dc-cc81c77b7f25
                    name: RC-01001
                    datasetId: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                    createdOn: 2022-05-02T01:14:34.366Z
                meta:
                  limit: 50
                  offset: 0
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
    post:
      tags:
        - Collection
      summary: Create a new collection
      description: Adds a new collection to a dataset. If the new collection already
        exists in the dataset then no action is taken.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/postCollectionSuccessSchema"
              example:
                id: 054bf4c2-84cc-4d30-b4dc-cc81c77b7f25
                name: RC-01001
                datasetId: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                createdOn: 2022-05-02T01:14:34.366Z
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/postCollectionBodySchema"
            example:
              workspaceName: Firefly Resource Development
              datasetName: Drilling Chips
              name: RC-01001
  /dataset:
    get:
      tags:
        - Dataset
      summary: Search for datasets
      description: Searches for a list of matching datasets. Each dataset is described
        by its name and id.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
        - name: name
          in: query
          description: Search pattern to match dataset names
          required: false
          schema:
            type: string
        - name: match
          in: query
          description: "Determines how the search pattern matches the dataset name.
            Wildcards '*' can be used with the 'like' match.<br><br>Default
            value: 'equals'.<br><br>Allowed values: 'equals', 'startswith',
            'endswith', 'includes', 'like'."
          required: false
          schema:
            type: string
        - name: workspaceid
          in: query
          description: Only search within this workspace.
          required: false
          schema:
            type: string
        - name: workspacename
          in: query
          description: Only search within this workspace.
          required: false
          schema:
            type: string
        - name: offset
          in: query
          description: Return datasets starting at this offset.
          required: false
          schema:
            type: number
        - name: limit
          in: query
          description: Limit how many datasets are returned.
          required: false
          schema:
            type: number
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/datasetSuccessSchema"
              example:
                - id: 054bf4c2-84cc-4d30-b4dc-cc81c77b7f25
                  name: Dataset-001
                  workspaceId: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                  createdOn: 2022-05-02T01:14:34.366Z
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
    post:
      tags:
        - Dataset
      summary: Create a new dataset
      description: Adds a new dataset to a workspace. If the new dataset already
        exists in the workspace then no action is taken.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/datasetSuccessSchema"
              example:
                id: 054bf4c2-84cc-4d30-b4dc-cc81c77b7f25
                name: Dataset-001
                workspaceId: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                createdOn: 2022-05-02T01:14:34.366Z
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
      requestBody:
        required: true
        content:
          application/json:
            example:
              - workspaceId: 43c5b45f-913a-483c-9991-4f4766bc0fef
                name: Dataset-001
  /imagery:
    get:
      tags:
        - Imagery
      summary: Search for imagery
      description: Searches for a list of imageries matching a search criteria.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
        - name: workspaceName
          in: query
          description: Restrict searching to this workspace.
          required: true
          schema:
            type: string
        - name: datasetName
          in: query
          description: Restrict searching to this dataset.
          required: false
          schema:
            type: string
        - name: collectionName
          in: query
          description: Restrict searching to this collection. Either collection or
            workspace must always be defined.
          required: false
          schema:
            type: string
        - name: imageryTypeName
          in: query
          description: Only search for imagery with this imagery type. If not provided
            then all imagery types are returned.
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: Search for imagery with this name.
          required: false
          schema:
            type: string
        - name: startDepth
          in: query
          description: Search for imagery with this start depth.
          required: false
          schema:
            type: number
        - name: endDepth
          in: query
          description: Search for imagery with this end depth.
          required: false
          schema:
            type: number
        - name: x
          in: query
          description: Search for imagery with this longtitude/X coordinate.
          required: false
          schema:
            type: number
        - name: y
          in: query
          description: Search for imagery with this latitude/Y coordinate.
          required: false
          schema:
            type: number
        - name: z
          in: query
          description: Search for imagery with this elevation/Z coordinate.
          required: false
          schema:
            type: number
        - name: match
          in: query
          description: "Determines how the search pattern matches the start/end
            depths.<br>Default value: equals<br>Allowed values: 'equals',
            'includes'"
          required: false
          schema:
            type: string
        - name: tol
          in: query
          description: "Tolerance used when matching numbers.<br>Default value: 0.0"
          required: false
          schema:
            type: number
        - name: updatedSince
          in: query
          description: Only return imagery that has been updated in the last number of
            specified days.
          required: false
          schema:
            type: number
        - name: uploadedSince
          in: query
          description: Only return imagery that has had images uploaded in the last number
            of specified days.
          required: false
          schema:
            type: number
        - name: offset
          in: query
          description: Return imagery starting at this offset.
          required: false
          schema:
            type: number
        - name: limit
          in: query
          description: Limit how many imageries are returned. The default and maximum
            setting restricts the output to 5000 imageries.
          required: false
          schema:
            type: number
        - name: verbose
          in: query
          description: "Return all named keys identifying each imagery. IMPORTANT: For
            compatibility reasons, this must be set to be true otherwise not all
            information is returned."
          required: true
          schema:
            type: boolean
        - name: includeFeatures
          in: query
          description: Include featureDefinitions in returned imagery payload. Defaults to
            true. Recommended to set this to false if you do not need the
            features.
          required: false
          schema:
            type: boolean
        - name: user-agent
          in: header
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imagerySuccessSchema"
              example:
                imageries:
                  - id: e2f26f0d-51c8-468e-b02f-29b4dc2217a2
                    collectionId: 054bf4c2-84cc-4d30-b4dc-cc81c77b7f25
                    imageryTypeId: 6a69bf8e-c03c-4ed2-8a62-d6feac838f12
                    workspaceId: a27b51bf-b918-4fb4-a28f-4f089bf646a8
                    workspaceName: Firefly Resource Development
                    datasetId: 71b93d30-8e5f-4b07-9f08-8e6bf5a72a50
                    datasetName: Drilling Chips
                    collectionName: RC-01001
                    imageryTypeName: Chips
                    startDepth: 5
                    endDepth: 15
                    updatedAt: 2011-10-05T14:48:00.000Z
                    images:
                      - id: 87a703c2-9bb4-4e56-951d-be293fb71692
                        imageTypeId: f16c5dbe-f455-4076-8358-ffda8f538814
                        url: https://imago.api.seequent.com/integrate/2/image/b91119e8-cee5-4c11-ad14-fe1dcb0c1c66/?userId=34a3f4ae-d53c-43d4-8545-a552c2a24c54&start=2025-04-23T03:59:36.499Z&expiry=2025-04-23T15:59:36.499Z&sig=4284b5576fffd3ebb94740025415aa2138d514139c5c61c5ef0b7af912da3fb8
                        uploadedOn: 2022-05-02T06:25:32.085Z
                        uploadedBy: ImagoLive
                        mimeType: image/jpeg
                        fileSize: "40192"
                        width: null
                        height: null
                        checksum: x7Rpt+5ET3C3vQataO7tEA==
                        imageTypeName: Wet
                        updatedAt: 2011-10-05T14:48:00.000Z
                    attributeDefinitions:
                      - name: Core Tray Box Numbers
                        attributes:
                          StartBox: 2
                          EndBox: 2
                    featureDefinitions:
                      - name: Linearization
                        featureTypes:
                          - name: row
                            images:
                              - name: Wet Original
                                features:
                                  - points:
                                      - x: 0.007876626215875149
                                        y: 0.3148634731769562
                                        pen: 0
                                      - x: 0.9640294909477234
                                        y: 0.3148634731769562
                                        pen: 1
                                      - x: 0.9640294909477234
                                        y: 0.7148634731769562
                                        pen: 1
                                      - x: 0.00787662621587514
                                        y: 0.7148634731769562
                                        pen: -1
                meta:
                  limit: 50
                  offset: 0
        "401":
          description: Unauthorized
        "404":
          description: Internal error occurred during the request.
        "500":
          description: Internal Server Error
    put:
      tags:
        - Imagery
      summary: Update an imagery details and attributes
      description: Update an imagery attributes and identification.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/putImageryBodySchema"
            example:
              - keys:
                  workspaceName: Firefly Resource Development
                  datasetName: Drilling Chips
                  collectionName: RC-01001
                  imageryTypeName: Chips
                  startDepth: 0
                  endDepth: 10
                startDepth: 5
                endDepth: 15
                attributeDefinitions:
                  - name: Core Tray Box Numbers
                    attributeValues:
                      StartBox: 2
                      EndBox: 2
                featureDefinitions:
                  - name: Linearization
                    featureTypes:
                      - name: row
                        images:
                          - name: Wet Original
                            features:
                              - points:
                                  - x: 0.007876626215875149
                                    y: 0.3148634731769562
                                    pen: 0
                                  - x: 0.9640294909477234
                                    y: 0.3148634731769562
                                    pen: 1
                                  - x: 0.9640294909477234
                                    y: 0.7148634731769562
                                    pen: 1
                                  - x: 0.00787662621587514
                                    y: 0.7148634731769562
                                    pen: -1
    post:
      tags:
        - Imagery
      summary: Create a new imagery
      description: This will create a new imagery if it does not exist, otherwise it
        will update an existing imagery.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: Successful response.
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/postImageryBodySchema"
            example:
              - keys:
                  workspaceName: Firefly Resource Development
                  datasetName: Drilling Chips
                  collectionName: RC-01001
                  imageryTypeName: Chips
                  startDepth: 0
                  endDepth: 10
                attributeDefinitions:
                  - name: Core Tray Box Numbers
                    attributeValues:
                      StartBox: 1
                      EndBox: 1
                featureDefinitions:
                  - name: Linearization
                    featureTypes:
                      - name: row
                        images:
                          - name: Wet Original
                            features:
                              - points:
                                  - x: 0.007876626215875149
                                    y: 0.3148634731769562
                                    pen: 0
                                  - x: 0.9640294909477234
                                    y: 0.3148634731769562
                                    pen: 1
                                  - x: 0.9640294909477234
                                    y: 0.7148634731769562
                                    pen: 1
                                  - x: 0.00787662621587514
                                    y: 0.7148634731769562
                                    pen: -1
  /image:
    get:
      tags:
        - Image
      summary: Download an image from an imagery
      description: Downloads an image. While the only required query parameters are
        collection name, imagery type name, and image type name, you must
        provide enough additional information to identify a single imagery in
        the collection that contains the desired image through one of the
        following methods:<br /> a) the imagery's name, using the 'name' query
        parameter,<br /> b) the imagery's depth interval, using the 'startDepth'
        and optionally 'endDepth' query parameters, or <br /> c) the imagery's
        unique id, using the 'imageryId' query parameter.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
        - name: workspaceName
          in: query
          description: Search for this workspace.
          required: false
          schema:
            type: string
        - name: datasetName
          in: query
          description: Search for this dataset.
          required: false
          schema:
            type: string
        - name: collectionName
          in: query
          description: Search for this collection.
          required: true
          schema:
            type: string
        - name: imageryTypeName
          in: query
          description: Search for an imagery with this imagery type.
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: Search for imagery by name.
          required: false
          schema:
            type: string
        - name: startDepth
          in: query
          description: Search for imagery by start depth.
          required: false
          schema:
            type: number
        - name: endDepth
          in: query
          description: Search for imagery by end depth.
          required: false
          schema:
            type: number
        - name: imageTypeName
          in: query
          description: Search for an image of this image type in the imagery.
          required: true
          schema:
            type: string
        - name: width
          in: query
          description: Scale the image to this width (height is adjusted according to
            aspect ratio if not specified).
          required: false
          schema:
            type: number
        - name: height
          in: query
          description: Scale the image to this height (width is adjusted according to
            aspect ratio if not specified).
          required: false
          schema:
            type: number
      responses:
        "200":
          description: Successful response.
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
    post:
      tags:
        - Image
      summary: Upload an image to an imagery
      description: Uploads an image of a specified image type to an imagery.
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
        - name: workspaceName
          in: query
          description: Search for this workspace.
          required: false
          schema:
            type: string
        - name: datasetName
          in: query
          description: Search for this dataset.
          required: false
          schema:
            type: string
        - name: collectionName
          in: query
          description: Search for this collection.
          required: true
          schema:
            type: string
        - name: imageryTypeName
          in: query
          description: Search for an imagery with this imagery type.
          required: true
          schema:
            type: string
        - name: name
          in: query
          description: Search for imagery by name.
          required: false
          schema:
            type: string
        - name: startDepth
          in: query
          description: Search for imagery by start depth.
          required: false
          schema:
            type: number
        - name: endDepth
          in: query
          description: Search for imagery by end depth.
          required: false
          schema:
            type: number
        - name: x
          in: query
          description: Search for imagery by longtitude/X.
          required: false
          schema:
            type: number
        - name: y
          in: query
          description: Search for imagery by latitude/Y.
          required: false
          schema:
            type: number
        - name: z
          in: query
          description: Search for imagery by elevation/Z.
          required: false
          schema:
            type: number
        - name: imageTypeName
          in: query
          description: Add an image of this image type.
          required: true
          schema:
            type: string
        - name: mimeType
          in: query
          description: "Image's mime type<br>Allowed values: 'image/png', 'image/jpeg'"
          required: true
          schema:
            type: number
      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/postImageSuccessSchema"
              example:
                imageId: 4dba5ebd-264f-4135-8420-1293f61c4e59
                imageryId: c2019bd6-34aa-4561-ab2f-8802fa5ff3a9
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
  /dataset/{datasetId}/imageryType/{imageryTypeId}:
    post:
      tags:
        - Dataset
      summary: Assign an Imagery Type to a Dataset
      description: Links the provided imageryTypeId to the provided datasetId.
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: The ID of the dataset to link.
        - name: imageryTypeId
          in: path
          required: true
          schema:
            type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: The ID of the imagery type to link.
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: The imagery type was successfully linked to the dataset.
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
  /imageryType:
    get:
      tags:
        - Imagery Type
      summary: Retrieves a list of Imagery Types
      description: Retrieves a list of Imagery Types
      parameters:
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "200":
          description: The imagery type list was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imageryTypeSuccessSchema"
              example:
                - id: 78dee0d8-efe9-443c-b606-b30e1e7413fb
                  name: Standard CoreBox Imagery Type
                  contentType: coretray
                  geometryType: trace
                  coordinateType: geographic
                  enableAutoCrop: false
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed.
        "500":
          description: Internal error occurred during the request.
  /imagery/{imageryid}:
    delete:
      tags:
        - Imagery
      summary: Delete an imagery
      description: Deletes an imagery based on the provided imagery ID.
      parameters:
        - name: imageryid
          in: path
          required: true
          schema:
            type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: The ID of the imagery to delete.
        - name: imago-api-token
          in: header
          required: true
          example: b4ecb7d7-b8bb-460f-9506-134df358f471
          schema:
            type: string
      responses:
        "204":
          description: The imagery was successfully deleted.
        "401":
          description: Unauthorized
        "422":
          description: The request could not be completed using the supplied parameters.
        "500":
          description: Internal error occurred during the request.
components:
  schemas:
    postSessionBodySchema:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: User's account name.
        password:
          type: string
          description: User's password.
    postSessionSuccessSchema:
      type: object
      required:
        - uid
        - apiToken
      properties:
        uid:
          type: string
          description: User's identifier.
        apiToken:
          type: string
          description: Imago authorisation token.
    getSessionSuccessSchema:
      type: object
      required:
        - uid
      properties:
        uid:
          type: string
          description: User's identifier.
    getUserContextSuccessSchema:
      type: object
      required:
        - workspaces
      properties:
        workspaces:
          description: List of workspaces accessible by the signed in user.
          type: array
          items:
            $ref: "#/components/schemas/workspacesSchema"
    workspacesSchema:
      type: object
      required:
        - id
        - name
        - readonly
        - datasets
      properties:
        id:
          description: Workspace identifier.
          type: string
        name:
          description: Name of the workspace.
          type: string
        readonly:
          description: Indicates whether the person has readonly or write access to
            workspace.
          type: string
        datasets:
          description: List of datasets in the workspace.
          type: array
          items:
            $ref: "#/components/schemas/datasetsSchema"
    datasetsSchema:
      type: object
      required:
        - id
        - name
        - imageryTypes
      properties:
        id:
          description: Dataset identifier.
          type: string
        name:
          description: Name of the dataset.
          type: string
        imageryTypes:
          description: List of imagery types in the dataset.
          type: array
          items:
            $ref: "#/components/schemas/imageryTypesSchema"
    imageryTypesSchema:
      type: object
      required:
        - id
        - name
        - contentType
        - geometryType
        - coordinateType
        - imagetypes
        - attributeDefinitions
        - labelDefinitions
        - featureDefinitions
        - enableAutoCrop
      properties:
        id:
          description: Imagery type identifier.
          type: string
        name:
          description: Name of the imagery type.
          type: string
        contentType:
          description: Content type of the imagery type.
          type: string
        geometryType:
          description: Geometry type of the imagery type.
          type: string
        coordinateType:
          description: Use geographic or geometric coordinates.
          type: string
        imagetypes:
          description: List of image types in the imagery type.
          type: array
          items:
            $ref: "#/components/schemas/imagetypesSchema"
        attributeDefinitions:
          description: List of attribute definitions assigned to the imagery type.
          type: array
          items:
            $ref: "#/components/schemas/getUserContextAttributeDefinitionsSchema"
        labelDefinitions:
          description: List of label definitions assigned to the imagery type.
          type: array
          items:
            $ref: "#/components/schemas/labelDefinitionsSchema"
        featureDefinitions:
          description: List of feature definitions assigned to the imagery type.
          type: array
          items:
            $ref: "#/components/schemas/featureDefinitionsSchema"
        enableAutoCrop:
          description: Indicates whether AutoCrop is enabled for this imagery type.
          type: string
    imagetypesSchema:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: Image type identifier.
          type: string
        name:
          description: Name of the image type.
          type: string
        dataType:
          description: Data type of the image type.
          type: string
        sourceType:
          description: Source type of the image type.
          type: string
        baseImageTypeName:
          description: Name of the base image type.
          type: string
    getUserContextAttributeDefinitionsSchema:
      type: object
      required:
        - name
        - attributeTypes
      properties:
        name:
          description: Name of the attribute definition.
          type: string
        attributeTypes:
          description: List of attribute types in the attribute definition.
          type: array
          items:
            $ref: "#/components/schemas/attributeTypesSchema"
    attributeTypesSchema:
      type: object
      required:
        - name
        - dataType
      properties:
        name:
          description: Name of the attribute type.
          type: string
        dataType:
          description: Data type for the value stored in the attribute type.
          type: string
          enum:
            - string
            - number
            - note
            - date
    labelDefinitionsSchema:
      type: object
      required:
        - name
        - labelTypes
      properties:
        name:
          description: Name of the label definition.
          type: string
        labelTypes:
          description: List of label types in the label definition.
          type: array
          items:
            $ref: "#/components/schemas/labelTypesSchema"
    labelTypesSchema:
      type: object
      required:
        - name
      properties:
        name:
          description: Name of the label type.
          type: string
    featureDefinitionsSchema:
      type: object
      required:
        - name
        - featureTypes
      properties:
        name:
          description: Name of the feature definition.
          type: string
        featureTypes:
          description: List of feature types in the feature definition.
          type: array
          items:
            $ref: "#/components/schemas/featureTypesSchema"
    featureTypesSchema:
      type: object
      required:
        - name
        - images
      properties:
        name:
          description: Name of the feature type.
          type: string
        images:
          description: images object with features.
          type: array
          items:
            $ref: "#/components/schemas/imagesFeaturesSchema"
    imagesFeaturesSchema:
      type: object
      required:
        - name
        - features
      properties:
        name:
          description: Name of the image type.
          type: string
        features:
          description: List of features in the image type.
          type: array
          items:
            $ref: "#/components/schemas/featuresSchema"
    featuresSchema:
      type: object
      required:
        - points
      properties:
        points:
          description: List of points that describe the geometry of the feature on the
            image.
          type: array
          items:
            $ref: "#/components/schemas/pointsSchema"
    pointsSchema:
      type: object
      required:
        - x
        - y
        - pen
      properties:
        x:
          description: The x value for the point as a percentage of the image width,
            between 0 (left border) and 1 (right border)
          type: number
        y:
          description: The y value for the point as a percentage of the image height,
            between 0 (top border) and 1 (bottom border)
          type: number
        pen:
          description: Describes the location of this point in relation to the drawing. 0
            for the first point, 1 for a middle point, and -1 for the last
            point.
          type: number
    postCollectionBodySchema:
      type: object
      required:
        - workspaceName
        - datasetName
        - name
      properties:
        workspaceName:
          description: Name of workspace for the new collection.
          type: string
        datasetName:
          description: Name of dataset for the new collection.
          type: string
        name:
          description: Name of new collection.
          type: string
    postCollectionSuccessSchema:
      type: object
      required:
        - id
        - name
        - datasetId
        - createdOn
      properties:
        id:
          description: New collection identifier.
          type: string
        name:
          description: Name of new collection.
          type: string
        datasetId:
          description: Identifier of dataset that the collection belongs to.
          type: string
        createdOn:
          description: Date/time when the collection was created.
          type: string
    getCollectionSuccessSchema:
      type: object
      required:
        - collections
      properties:
        collections:
          description: List of matching collections
          type: array
          items:
            $ref: "#/components/schemas/collectionSchema"
        meta:
          $ref: "#/components/schemas/paginationMetaSchema"
    collectionSchema:
      type: object
      required:
        - id
        - name
        - datasetId
        - createdOn
      properties:
        id:
          type: string
          description: Collection identifier
        name:
          type: string
          description: Name of collection
        datasetId:
          type: string
          description: Identifier of dataset that the collection belongs to
        createdOn:
          type: string
          description: Date/time when the collection was created.
    imageryTypeSuccessSchema:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            example: 78dee0d8-efe9-443c-b606-b30e1e7413fb
          name:
            type: string
            example: Standard CoreBox Imagery Type
          contentType:
            type: string
            example: coretray
          geometryType:
            type: string
            example: trace
          coordinateType:
            type: string
            example: geographic
          enableAutoCrop:
            type: boolean
            example: false
    imagerySuccessSchema:
      type: object
      required:
        - imageries
      properties:
        imageries:
          description: List of matching imagery
          type: array
          items:
            $ref: "#/components/schemas/imageriesSchema"
        meta:
          $ref: "#/components/schemas/paginationMetaSchema"
    imageriesSchema:
      type: object
      required:
        - id
        - workspaceName
        - datasetName
        - collectionName
        - imageryTypeName
        - images
        - attributeDefinitions
        - featureDefinitions
      properties:
        id:
          description: Imagery identifier.
          type: string
        workspaceName:
          description: Workspace name that the imagery belongs to.
          type: string
        datasetName:
          description: Dataset name that the imagery belongs to.
          type: string
        collectionName:
          description: Collection name that the imagery belongs to.
          type: string
        ImageryTypeName:
          description: Imagery type name that the imagery belongs to within the collection.
          type: string
        updatedAt:
          description: Last datetime that the imagery was updated.
          type: string
          format: date
        name:
          description: Name of the imagery
          type: string
        startDepth:
          description: Start depth of the imagery.
          type: number
        endDepth:
          description: End depth of the imagery.
          type: number
        x:
          description: Longtitude/X coordinate of the imagery.
          type: number
        y:
          description: Latitude/Y coordinate of the imagery.
          type: number
        z:
          description: Elevation/Z coordinate of the imagery.
          type: number
        images:
          description: List of images on this imagery.
          type: array
          items:
            $ref: "#/components/schemas/imagesSchema"
        attributeDefinitions:
          description: List of attribute definitions used by the imagery.
          type: array
          items:
            $ref: "#/components/schemas/getImageryAttributeDefinitionsSchema"
        featureDefinitions:
          description: List of feature definitions used by the imagery
          type: array
          items:
            $ref: "#/components/schemas/imageryFeatureDefinitionsSchema"
    getImageryAttributeDefinitionsSchema:
      type: object
      required:
        - name
        - attributeValues
      properties:
        name:
          description: Name of the attribute definition.
          type: string
        attributeValues:
          description: Key/value pairs of attributes on the imagery.
          type: object
          additionalProperties:
            type:
              - string
              - number
    imagesSchema:
      type: object
      properties:
        id:
          description: Image identifier.
          type: string
        imageTypeName:
          description: Image type name available on the imagery.
          type: string
        url:
          description: Timed access to a URL to directly download the image.
          type: string
        uploadedOn:
          description: Date/time that the image was uploaded.
          type: string
          format: date
        uploadedBy:
          description: User account that uploaded the image.
          type: string
        mimeType:
          description: Image's mime type.
          type: string
        width:
          description: Image's width in pixels.
          type: number
        height:
          description: Image's height in pixels.
          type: number
        fileSize:
          description: Size of image file.
          type: number
        updatedAt:
          description: Last datetime that the image was updated.
          type: string
          format: date
    imageryAttributeDefinitionsSchema:
      type: object
      required:
        - name
        - attributes
      properties:
        name:
          description: Name of the attribute definition.
          type: string
        attributes:
          description: Key/value pairs of attributes on the imagery.
          type: object
          additionalProperties:
            type:
              - string
              - number
    postImageryBodySchema:
      type: array
      description: List of imageries to create or update.
      items:
        $ref: "#/components/schemas/postImageryListSchema"
    postImageryListSchema:
      type: object
      required:
        - keys
      properties:
        keys:
          $ref: "#/components/schemas/imageryKeysSchema"
        attributeDefinitions:
          description: List of attribute definitions to update on the imagery.
          type: array
          items:
            $ref: "#/components/schemas/imageryAttributeDefinitionsSchema"
        featureDefinitions:
          description: List of feature definitions to update on the imagery
          type: array
          items:
            $ref: "#/components/schemas/imageryFeatureDefinitionsSchema"
    putImageryBodySchema:
      description: List of imageries to create or update.
      type: array
      items:
        $ref: "#/components/schemas/putImageryListSchema"
    putImageryListSchema:
      type: object
      required:
        - keys
      properties:
        keys:
          $ref: "#/components/schemas/imageryKeysSchema"
        name:
          description: Name of imagery. Only optional according to the imagery type's
            geometry type.
          type: string
        startDepth:
          description: New start depth of imagery if required.
          type: number
        endDepth:
          description: New end depth of imagery if required.
          type: number
        x:
          description: New longtitude/X coordinate of imagery if required. Only optional
            according to the imagery type's geometry type.
          type: number
        y:
          description: New latitude/Y coordinate of imagery if required. Only optional
            according to the imagery type's geometry type.
          type: number
        z:
          description: New elevation/Z coordinate of imagery if required. Only optional
            according to the imagery type's geometry type.
          type: number
        attributeDefinitions:
          description: List of attribute definitions to update on the imagery.
          type: array
          items:
            $ref: "#/components/schemas/imageryAttributeDefinitionsSchema"
        featureDefinitions:
          description: List of feature definitions to update on the imagery
          type: array
          items:
            $ref: "#/components/schemas/imageryFeatureDefinitionsSchema"
    imageryKeysSchema:
      type: object
      required:
        - collectionName
        - imageryTypeName
      properties:
        workspaceName:
          description: Name of the workspace containing the imagery. Only optional if
            updating an existing imagery.
          type: string
        datasetName:
          description: Name of the dataset containing the imagery. Only optional if
            updating an existing imagery.
          type: string
        collectionName:
          description: Name of the collection containing the imagery.
          type: string
        imageryTypeName:
          description: Name of the imagery type for the imagery.
          type: string
        name:
          description: Name of imagery. Only optional according to the imagery type's
            geometry type
          type: string
        startDepth:
          description: Start depth of imagery. Only optional according to the imagery
            type's geometry type.
          type: number
        endDepth:
          description: End depth of imagery. Only optional according to the imagery type's
            geometry type.
          type: number
        x:
          description: Longtitude/X coordinate of imagery. Only optional according to the
            imagery type's geometry type.
          type: number
        y:
          description: Latitude/Y coordinate of imagery. Only optional according to the
            imagery type's geometry type.
          type: number
        z:
          description: Elevation/Z coordinate of imagery. Only optional according to the
            imagery type's geometry type.
          type: number
    imageryFeatureDefinitionsSchema:
      type: object
      required:
        - name
        - featureTypes
      properties:
        name:
          description: Name of an existing Feature Definition
          type: string
        featureTypes:
          description: List of feature types linked to the feature definition containing
            the values to be saved
          type: array
          items:
            $ref: "#/components/schemas/imageryFeatureDefinitionsFeatureTypesSchema"
    imageryFeatureDefinitionsFeatureTypesSchema:
      type: object
      required:
        - name
        - images
      properties:
        name:
          description: Name of an existing Feature Type
          type: string
        images:
          description: List of images in the imagery with features, identified by image type
          type: array
          items:
            $ref: "#/components/schemas/imageryFeatureDefinitionsImagesSchema"
    imageryFeatureDefinitionsImagesSchema:
      type: object
      required:
        - name
        - features
      properties:
        name:
          description: Name of an Image Type linked to the Imagery Type
          type: string
        features:
          description: List of features present in the image
          type: array
          items:
            $ref: "#/components/schemas/imageryPointsArraySchema"
    imageryPointsArraySchema:
      type: object
      required:
        - points
      properties:
        points:
          description: A list of points that describe the geometry of the feature on the
            image
          type: array
          items:
            $ref: "#/components/schemas/imageryPointsSchema"
    imageryPointsSchema:
      type: object
      required:
        - x
        - y
        - pen
      properties:
        x:
          description: The x value for the point as a percentage of the image width,
            between 0 (left border) and 1 (right border)
          type: number
        y:
          description: The y value for the point as a percentage of the image height,
            between 0 (top border) and 1 (bottom border)
          type: number
        pen:
          description: Describes the location of this point in relation to the drawing. 0
            for the first point, 1 for a middle point, and -1 for the last
            point.
          type: number
    postImageSuccessSchema:
      type: object
      required:
        - imageryId
        - imageId
      properties:
        imageryId:
          description: New imagery's identifier (related to start/end depth, x/y/z etc..).
          type: string
        imageId:
          description: New image's identifier (related to image attached to imagery)
          type: string
    datasetSuccessSchema:
      type: object
      required:
        - id
        - name
        - workspaceId
        - createdOn
      properties:
        id:
          description: Dataset identifier.
          type: string
        name:
          description: Name of the dataset.
          type: string
        workspaceId:
          description: Identifier of the workspace that the dataset belongs to.
          type: string
        createdOn:
          description: Date/time when the dataset was created.
          type: string
    paginationMetaSchema:
      type: object
      properties:
        limit:
          type: integer
          description: The maximum number of items to return. Optional.
          example: 100
        offset:
          type: integer
          description: The number of items to skip before starting to collect the result
            set.
          example: 0
