openapi: 3.0.0
info:
    version: 0.4.0
    title: Dougal API
    description: >
        Public API of the Dougal seismic production & data analysis tool.

        This API may be used by anyone authorised to access a Dougal system. Access via a client other than the official web frontend is supported provided that it is done in line with this document and the use is not abusive or disruptive and doesn't inconvenience other users.

        ## Logging in

        All endpoints require a valid login for authentication and/or authorisation. Some endpoints may require elevated privileges.

        Log in may be explicit, by using the appropriate endpoint and presenting valid user credentials, or implicit by making a request from an authorised network or host. In the latter case, a session token will be returned in a `Set-Cookie` response header, along with the relevant response data. Users should expect a `Set-Cookie` header containing a cookie named `JWT` at any point during their interaction with the API and, upon receiving one, they should use the value contained therein as a token to be presented in subsequent requests until a new token is received. No state is kept server-side concerning user sessions.

        ### User roles

        There are three categories of user supported by the Dougal system in this version of the API, these are called ‘roles’ and are as follows:

        * `guest` role: has read-only access (`GET` endpoints).

        * `user` role: has read and write access to endpoints not dealing with administrative data.

        * `master` role: has read and write access to the same endpoints as the `user` role and to additional endpoints dealing with administrative data, such as the ability to set the system's configuration, define new surveys, etc. Note that currently no endpoints exist requiring `master` access.

        ### Logging out

        Albeit there is no explicit need to log out given the token-based, stateless authentication and authorisation architecture, a convenience endpoint is provided that will cause a browser to expire the `JWT` authentication cookie.

    contact:
        name: Dougal support
        email: dougal-support@aaltronav.eu
        url: https://gitlab.com/wgp/dougal/software/-/issues
servers:
    -   url: https://dougal.aaltronav.eu/api
        description: Dougal demo server
    -   url: https://248.dougal.aaltronav.eu/api
        description: Crew 248, external access
    -   url: https://lan.248.dougal.aaltronav.eu/api
        description: Crew 248, LAN access only

tags:
    -
        name: project
        description: Project-related information
    -
        name: preplot
        description: Preplot data
    -
        name: sequences
        description: Raw and final sequence data, and online information
    -
        name: planner
        description: Sequences planned to be shot
    -
        name: log
        description: Project events log
    -
        name: qc
        description: Project quality control definition and results
    -
        name: metadata
        description: Project items metadata
    -
        name: navdata
        description: Data from navigation headers
    -
        name: asaqc
        description: |
            Interface to [Equinor](https://equinor.com/)'s [ASAQC Vessel Track](https://api.equinor.com/docs/services/vessel-track/) application programming interface.

            Used for transferring line log data from the vessel to the Equinor office. As implemented as of October 2021, for each sequence that is queued for sending it transfers the following files:

            * SeisJSON file containing sequence event data.
            * PDF file which is a representation of the corresponding SeisJSON.
    -
        name: configuration
        description: Dougal instance configuration endpoints.
    -
        name: users
        description: User management
    -
        name: misc
        description: Miscellaneous endpoints

components:
    securitySchemes:

        # Read-only access
        BearerAuthGuest:
            type: http
            scheme: bearer
            bearerFormat: JWT
            description: >
                This authentication is used by users having the `guest` role, giving read-only access to the Dougal system. A token may be obtained by either explicitly logging in with authorised credentials or by making the request from an authorised network or host – in the latter case, a session token will be returned along with the first response in a `Set-Cookie` header.

                Tokens are valid for a limited amount of time. After this has elapsed, a new token will be generated for network- or host-authorised users. Users with explicitly initiated logins will have to reauthenticate.

                Users may present the returned token in an `Authorization: Bearer …` header or as a cookie, whichever is most convenient.
        CookieAuthGuest:
            type: apiKey
            in: cookie
            name: JWT
            description: >
                This authentication is used by users having the `guest` role, giving read-only access to the Dougal system. A token may be obtained by either explicitly logging in with authorised credentials or by making the request from an authorised network or host – in the latter case, a session token will be returned along with the first response in a `Set-Cookie` header.

                Tokens are valid for a limited amount of time. After this has elapsed, a new token will be generated for network- or host-authorised users. Users with explicitly initiated logins will have to reauthenticate.

                Users may present the returned token in an `Authorization: Bearer …` header or as a cookie, whichever is most convenient.


        # Read-write access
        BearerAuthUser:
            type: http
            scheme: bearer
            bearerFormat: JWT
            description: >
                This authentication is used by users having the `user` role, giving read and write access to the Dougal system, except for administrative endpoints. See the description of `BearerAuthGuest` for more information on how to obtain a token.
        CookieAuthUser:
            type: apiKey
            in: cookie
            name: JWT
            description: >
                This authentication is used by users having the `user` role, giving read and write access to the Dougal system, except for administrative endpoints. See the description of `CookieAuthGuest` for more information on how to obtain a token.


        # Read-write access
        BearerAuthAdmin:
            type: http
            scheme: bearer
            bearerFormat: JWT
            description: >
                This authentication is used by users having the `admin` role, giving read and write access to the Dougal system, including administrative endpoints. See the description of `BearerAuthGuest` for more information on how to obtain a token.
        CookieAuthAdmin:
            type: apiKey
            in: cookie
            name: JWT
            description: >
                This authentication is used by users having the `admin` role, giving read and write access to the Dougal system, including administrative endpoints. See the description of `CookieAuthGuest` for more information on how to obtain a token.

    responses:
        "400":
            description: >
                There was a problem with the syntax or the data of the request. Additional information may be provided in the response body.
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            message:
                                type: string

        "401":
            description: Unauthorised. Either no credentials were provided or the user does not have sufficient privileges to perform this operation.
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            message:
                                type: string

        "404":
            description: >
                Not found. Also returned when the user does not sufficient access rights to it
                and the server does not wish to reveal the resource's existence.

        "412":
            description: >
                [Precondition failed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412).
                The [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
                value does not match the current [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
                value of the resource.
                Typically this occurs when the resource has been modified and the request is not using the latest value.

        "428":
            description: >
                [Precondition Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428).
                This endpoint requires an [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
                and the request did not provide one.


    parameters:
        Project:
            description: Alphanumeric identifier for a project.
            name: project
            in: path
            schema:
                type: string
            required: true
            example: eq20211

        Line:
            description: Preplot line number
            name: line
            in: path
            schema:
                type: integer
            required: true
            example: 5210

        Point:
            description: Preplot point number
            name: point
            in: path
            schema:
                type: integer
            required: true
            example: 2576

        Sequence:
            description: Sequence number
            name: sequence
            in: path
            schema:
                type: integer
            required: true
            example: 115

        Shotpoint:
            description: Shotpoint number
            name: shot
            in: path
            schema:
                type: integer
            required: true
            example: 2576

        EventID:
            description: Event ID
            name: id
            in: path
            schema:
                type: integer
            required: true
            example: 14707

        Since:
            description: Starting epoch
            name: since
            in: path
            schema:
                type: string
                format: date-time
            required: true
            example: 1970-01-01T00:00:00Z

        QueryLimit:
            description: Maximum number of results to return
            name: limit
            in: query
            schema:
                type: integer

        QueryOffset:
            description: The number of items to skip before starting to collect the result set
            name: offset
            in: query
            schema:
                type: integer

        QueryProject:
            description: |
                Subset of attributes to be returned.

                Some endpoints can perform [projections](https://en.wikipedia.org/wiki/Projection_(relational_algebra)) on their result sets. This parameter controls the set of attributes that are to be returned. Its format is a string where each parameter name is separated by any of the following characters: space, comma, colon or semicolon. Attribute names are truncated at the first dot (`.`) if they contain any.
            name: project
            in: query
            schema:
                type: string
                pattern: "(([^\\s,;:]+)(\\s*[,;:\\s]\\s*)?)+"
            example: "line,point,tstamp"

        QueryMime:
            name: mime
            description: |
                Ask for the representation of the requested resource to be provided in the indicated MIME type. Overrides the [`Accept`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) request header values (if any).

                Note that the server is not obliged to honour the requested type and a default (usually `application/json`) might be provided instead. Always check the response's [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header.
            in: query
            schema:
                type: string

        QueryFilename:
            name: filename
            description: |
                Cause the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header to be set and suggest a file name to download as.

                Note that the [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) response header is not affected by this parameter.
            in: query
            schema:
                type: string

        CSVDelimiter:
            description: Delimiter value to use in CSV requests or responses.
            name: delimiter
            in: query
            schema:
                type: string
            example: ","

        CSVFields:
            description: Fields to return in CSV responses.
            name: fields
            in: query
            schema:
                type: string
            example: timestamp,sequence,point,text

        CSVHeader:
            description: Whether to return the header row in CSV responses. It defaults to **`true`**. If present, any value other than `true` or `1` represent **`false`**.
            name: header
            in: query
            schema:
                type: string
            example: f

        Unique:
            description: |
                Return unique results. Any value at all represents `true`.
            name: unique
            in: query
            schema:
                type: string
                pattern: ".+"
            example: "t"

        ETag:
            name: ETag
            in: header
            description: >
                Response [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header.
                Used when modifying a resource to detect conflicting updates.
            schema:
                type: string

        If-Match:
            name: If-Match
            in: header
            type: string
            description: >
                The [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header
                must match the `ETag` value of the corresponding GET request for the resource.
            required: true


    schemas:
        Duration:
            type: object
            nullable: true
            properties:
                hours:
                    type: integer
                minutes:
                    type: integer
                seconds:
                    type: integer
                milliseconds:
                    type: number

        # GeoJSON schemas come from http://schemas.opengis.net/ogcapi/
        GeoJSONPoint:
            $ref: "ogcapi/features/part1/1.0/openapi/schemas/pointGeoJSON.yaml"

        GeoJSONLinestring:
            $ref: "ogcapi/features/part1/1.0/openapi/schemas/linestringGeoJSON.yaml"

        GeoJSONFeature:
            $ref: "ogcapi/features/part1/1.0/openapi/schemas/featureGeoJSON.yaml"

        Label:
            type: object
            properties:
                name:
                    type: string
                    description: The label's name. Uniqueness is not enforced but non-unique label names may cause unexpected results.
                    example: Nav
                data:
                    description: Label metadata
                    type: object
                    properties:
                        view:
                            description: Visual attributes
                            type: object
                            properties:
                                colour:
                                    type: string
                                    description: "Label colour. Either an hex colour or a colour name."
                                    example: "#EF9A9A"
                                description:
                                    type: string
                                    description: A short textual description for the label. May be shown as a tooltip by user agents.
                                    example: Navigation events
                model:
                    description: The label's data model
                    type: object
                    properties:
                        user:
                            type: boolean
                            description: "`true` if users can manually apply this label, `false` if this is a system label."
                        multiple:
                            type: boolean
                            description: "`true` if the label can appear multiple times in the same acquisition sequence; if `false`, any new instance of the label when applied to an acquisition sequence will cause the old instance to be removed."

        PresetRemark:
            description: |
                A canonical way to describe an event.

                The aim of preset remarks is to reduce ambiguity and assist users who may not be fully conversant
                with the language being used.
            type: object
            properties:
                text:
                    type: string
                    description: |
                        If this instance has no child items, this is the textual content of the remark.

                        If there are child items, this is a description of the child items. Preset remark
                        lists are intended to be presented in user interfaces as a multi-level menu or
                        similar element.
                labels:
                    description: |
                        Labels associated with this remark or with its child items.
                        If the text matches a predefined label name, that will be used, else a default label
                        will be created.
                    type: array
                    items:
                        type: string
                items:
                    description: For convenience and accessibility, remarks may be grouped hierarchically.
                    type: array
                    items:
                        $ref: "#/components/schemas/PresetRemark"

        PresetRemarksList:
            description: A list of preset remarks.
            type: array
            items:
                $ref: "#/components/schemas/PresetRemark"

        PresetRemarksSet:
            description: |
                Preset remarks may be grouped into *sets*, and these sets imported into individual projects,
                or different sets may be presented to different users depending on their role, etc.
            type: object
            properties:
                name:
                    type: string
                description:
                    type: string
                items:
                    type: array
                    items:
                        $ref: "#/components/schemas/PresetRemark"


        AbstractDelimitedStringDecoderFieldDefinition:
            # Only the required properties of the field definition object
            type: object
            required: [ column ]
            properties:
                column:
                    description: Zero-based field index
                    type: number
                    minimum: 0


        DelimitedStringDecoderFieldDefinition:
            allOf:
                - $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
                -
                    type: object
                    description: Arbitrary properties
                    required: [ offset, length ]
                    properties:
                        type:
                            description: |
                                Type of field. An attempt will be made to convert the value from a text string to one the following:

                                Value   | Type
                                --------|-----
                                `int`   | An integer
                                `float` | A floating point number
                                `bool`  | A boolean (**true** or **false**)
                                `str`   | A text string
                            type: string
                            default: str
                            enum:
                                - int
                                - float
                                - bool
                                - str
                        enum:
                            description: |
                                Match the field against a list of predefined values and transform the output if one matches.
                            type: array
                            items:
                                -
                                    description: A key / value dictionary.
                                    type: object
                                    patternProperties:
                                        "^.+$":
                                            description: Replacement value if the key matches.
                                            type: string
                        default:
                            description: If this field cannot be decoded or none of the `enum` values match, assign this value to the field.
                            type: [ int, float, bool, str ]


        DelimitedStringDecoderDelimiterDefinition:
            type: string
            minLength: 1
            description: Delimiter character or sequence of characters.


        DelimitedStringDecoderDefinition:
            type: object
            required: [ fields ]
            properties:
                example:
                    type: string
                    description: A specimen piece of text that can be used to illustrate a typical form of the string to be decoded. The decoder is line-based but the example string can consist of multiple lines.
                delimiter:
                    $ref: "#/components/schemas/DelimitedStringDecoderDelimiterDefinition"
                fields:
                    type: object
                    description: A dictionary of property names and their definitions.
                    patternProperties:
                        "^.+$":
                            $ref: "#/components/schemas/DelimitedStringDecoderFieldDefinition"


        AbstractFixedStringDecoderFieldDefinition:
            # Only the required properties of the field definition object
            type: object
            required: [ offset, length ]
            properties:
                offset:
                    description: Offset in code points from the beginning of the line
                    type: number
                    minimum: 0
                length:
                    description: Length of this field in code points
                    type: number
                    minimum: 1


        FixedStringDecoderFieldDefinition:
            allOf:
                - $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
                -
                    type: object
                    description: Arbitrary properties
                    required: [ offset, length ]
                    properties:
                        type:
                            description: |
                                Type of field. An attempt will be made to convert the value from a text string to one the following:

                                Value   | Type
                                --------|-----
                                `int`   | An integer
                                `float` | A floating point number
                                `bool`  | A boolean (**true** or **false**)
                                `str`   | A text string
                            type: string
                            default: str
                            enum:
                                - int
                                - float
                                - bool
                                - str
                        enum:
                            description: |
                                Match the field against a list of predefined values and transform the output if one matches.
                            type: array
                            items:
                                -
                                    description: A key / value dictionary.
                                    type: object
                                    patternProperties:
                                        "^.+$":
                                            description: Replacement value if the key matches.
                                            type: string
                        default:
                            description: If this field cannot be decoded or none of the `enum` values match, assign this value to the field.
                            type: [ int, float, bool, str ]


        FixedStringDecoderDefinition:
            type: object
            required: [ fields ]
            properties:
                example:
                    type: string
                    description: A specimen piece of text that can be used to illustrate a typical form of the string to be decoded. The decoder is line-based but the example string can consist of multiple lines.
                fields:
                    type: object
                    description: A dictionary of property names and their definitions.
                    patternProperties:
                        "^.+$":
                            $ref: "#/components/schemas/FixedStringDecoderFieldDefinition"


        LineNameInfoDefinition:
            allOf:
                - $ref: "#/components/schemas/FixedStringDecoderDefinition"
                - description: |
                    Line or file name pattern.

                    Describes how a line or file name is to be decoded.
                - properties:
                    fields:
                        required: [ sequence ]
            example:
                example: EQ22200-2213130-007.000.P111
                fields:
                    line:
                        length: 4
                        type: int
                        offset: 10
                    sequence:
                        length: 3
                        type: int
                        offset: 16
                    incr:
                        enum:
                            "1": true
                            "2": false
                        length: 1
                        type: bool
                        offset: 8
                    attempt:
                        length: 1
                        type: int
                        offset: 14
                    file_no:
                        length: 3
                        type: int
                        offset: 20
                    year:
                        offset: 2
                        length: 2
                        type: int
                    survey_type:
                        enum:
                            "0": Marine
                            "2": OBS/PRM
                        offset: 4
                        length: 1
                        default: Unknown
                        type: str
                    project_number:
                        offset: 5
                        length: 2
                        type: int
                    num_sources:
                        enum:
                            "0": "2"
                            "1": "1"
                            "2": "3"
                        offset: 9
                        length: 1
                        type: int
                    direction:
                        enum:
                            "1": 62.10°
                            "2": 242.10°
                            "3": Orthogonal
                        offset: 8
                        length: 1


        RegExpPatternDefinition:
            type: object
            properties:
                regex:
                    type: string
                    description: A [JavaScript regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions), potentially containing [capture groups](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Groups_and_backreferences).
                flags:
                    type: string
                    description: Optional [flags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags) applying to the regular expression.
                captures:
                    description: |
                        Array of capture group names.

                        Each capture group in `regex` should have a corresponding entry in this array,
                        regardless of whether the group is actually used or not. For unused groups, a
                        non-unique name such as `(ignore)` is acceptable.
                    type: array
                    items:
                        type: string
                        description: Capture group name.

        DataFilePathSpecification:
            type: object
            properties:
                paths:
                    description: List of paths in which to search for matching files.
                    type: array
                    items:
                        type: string
                        description: Literal path name (globs not allowed here)
                globs:
                    description: |
                        File name globs.

                        Only files matching at least one of these globs inside one of the paths in `paths`
                        will be taken into account.
                    type: array
                    items:
                        type: string
                        description: "[Glob](https://tldp.org/LDP/abs/html/globbingref.html) pattern."
                lineNameInfo:
                    $ref: "#/components/schemas/LineNameInfoDefinition"
                pattern:
                    allOf:
                        - deprecated: true
                        - $ref: "#/components/schemas/RegExpPatternDefinition"
                        - description: |
                            File name pattern.

                            Files that pass the glob test must also match this regular expression pattern.
                            The regular expression may contain capture groups that will be used to extract
                            information from the file name. The pattern is applied to the base file name,
                            not to the full path.

        BinningGridDefinition:
            type: object
            description: Binning grid definition.
            properties:
                theta:
                    type: number
                    description: Direction of the I axis in degrees.
                I_inc:
                    type: number
                    description: I-axis increment.
                J_inc:
                    type: number
                    description: J-axis increment.
                I_width:
                    type: number
                    description: I-axis bin width. Dougal always assumes the I-axis to be the inline axis.
                J_width:
                    type: number
                    description: J-axis bin width.
                origin:
                    type: object
                    description: Bin grid origin
                    properties:
                        easting:
                            type: number
                            description: Origin Easting.
                        northing:
                            type: number
                            description: Origin Northing.
                        I:
                            type: number
                            description: I-axis value at origin.
                        J:
                            type: number
                            description: J-axis value at origin.


        PreplotFileSpecification:
            type: object
            description: Preplot file specification.
            required: [ path, class, type ]
            properties:
                path:
                    type: string
                    description: File system path to the file, from the point of view of the host Dougal server. The path must be a child of one of the paths listed in Dougal's global configuration under [`import.mounts`](https://gitlab.com/wgp/dougal/software/-/commit/811864123197099cc13375a914b6cf0fdaef6b22).
                class:
                    type: string
                    description: |
                        Preplot class:

                        - Source points (`S`)
                        - Vessel points (`V`)
                type:
                    type: string
                    description: File format.
            oneOf:
                -
                    title: Fixed width format
                    required: [ fields ]
                    properties:
                        class:
                            enum:
                                - S
                                - V
                        type:
                            const: fixed-width
                        fields:
                            type: object
                            description: A dictionary of property names and their definitions.
                            required: [ line_name, point_number, easting, northing ]
                            properties:
                                line_name:
                                    allOf:
                                        - description: Line name
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: int
                                        - $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
                                point_number:
                                    allOf:
                                        - description: Point number
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: int
                                        - $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
                                easting:
                                    allOf:
                                        - description: Easting grid value
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: float
                                        - $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
                                northing:
                                    allOf:
                                        - description: Northing grid value
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: float
                                        - $ref: "#/components/schemas/AbstractFixedStringDecoderFieldDefinition"
                            patternProperties:
                                "^.+$":
                                    $ref: "#/components/schemas/FixedStringDecoderFieldDefinition"
                -
                    title: Standard formats
                    properties:
                        class:
                            enum:
                                - S
                                - V
                        type:
                            enum:
                                - sps1
                                - sps2.1
                                - p190
                -
                    title: CSV
                    properties:
                        class:
                            enum:
                                - S
                                - V
                        type:
                            const: csv
                        delimiter:
                            $ref: "#/components/schemas/DelimitedStringDecoderDelimiterDefinition"
                        fields:
                            type: object
                            description: A dictionary of property names and their definitions.
                            required: [ line_name, point_number, easting, northing ]
                            properties:
                                line_name:
                                    allOf:
                                        - description: Line name
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: int
                                        - $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
                                point_number:
                                    allOf:
                                        - description: Point number
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: int
                                        - $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
                                easting:
                                    allOf:
                                        - description: Easting grid value
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: float
                                        - $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
                                northing:
                                    allOf:
                                        - description: Northing grid value
                                        -
                                            properties:
                                                type:
                                                    type: string
                                                    const: float
                                        - $ref: "#/components/schemas/AbstractDelimitedStringDecoderFieldDefinition"
                            patternProperties:
                                "^.+$":
                                    $ref: "#/components/schemas/DelimitedStringDecoderFieldDefinition"
                -
                    title: Sail lines
                    properties:
                        class:
                            description: Sail lines preplot class
                            const: saillines
                        type:
                            const: x-sl+csv
                -
                    title: Legacy format
                    deprecated: true
                    required: [ format ]
                    properties:
                        class:
                            enum:
                                - S
                                - V
                        type:
                            const: sps
                        format:
                            type: object
                            description: Fields format specification
                            required: [ widths, names, types ]
                            properties:
                                widths:
                                    type: array
                                    description: Array of field widths. A positive value denotes the width of the next valid field; a negative value skips that number of characters.
                                    items:
                                        - integer
                                names:
                                    type: array
                                    description: |
                                        Array of field names. Must contain at least the following values:

                                        - `line_name`
                                        - `point_number`
                                        - `easting`
                                        - `northing`

                                        It may contain additional fields, but those will not be interpreted or used by Dougal.
                                    items:
                                        - string
                                types:
                                    type: array
                                    description: |
                                        Array of field types. Must be one of the following:

                                        - `str`
                                        - `int`
                                        - `float`
                                    items:
                                        -
                                            type: string
                                            enum:
                                                - str
                                                - int
                                                - float


        PlannerSettings:
            description: Planner settings.
            type: object
            properties:
                defaultLineChangeDuration:
                    type: number
                    description: Default line change time (minutes)
                defaultAcquisitionSpeed:
                    type: number
                    description: Default line acquisition speed (knots)
                overlapBefore:
                    type: integer
                    description: Shots to overlap before a reshoot.
                overlapAfter:
                    type: integer
                    description: Shots to overlap after a reshoot.

        # LineNameInfo: TODO

        LineNameProperty:
            description: Description of a property available to include in a line name
            type: object
            properties:
                summary:
                    description: A short name for the property
                    type: string
                description:
                    description: A longer text describing the property
                    type: string
                type:
                    description: The property's type
                    type: string
                    enum:
                        - boolean
                        - number
                        - text
                format:
                    description: An optional format further constraining the type

        LineNameProperties:
            description: Properties available from the system to include in a line name
            type: object
            properties:
                line_number:
                    $ref: "#/components/schemas/LineNameProperty"
                sequence_number:
                    $ref: "#/components/schemas/LineNameProperty"
                original_sequence:
                    $ref: "#/components/schemas/LineNameProperty"
                pass_number:
                    $ref: "#/components/schemas/LineNameProperty"
                is_prime:
                    $ref: "#/components/schemas/LineNameProperty"
                is_reshoot:
                    $ref: "#/components/schemas/LineNameProperty"
                is_infill:
                    $ref: "#/components/schemas/LineNameProperty"
                direction:
                    $ref: "#/components/schemas/LineNameProperty"
                is_incrementing:
                    $ref: "#/components/schemas/LineNameProperty"
                text:
                    $ref: "#/components/schemas/LineNameProperty"

        LineNameBuilderField:
            description: Describes one of the elements making up a line name
            type: object
            properties:
                item:
                    description: |
                        Field item type.

                        Note that `text` is a special item type that
                        requires a value as part of its definition,
                        whereas for all other types a value is provided
                        by the system.
                    type: string
                    enum:
                        - line_number
                        - sequence_number
                        - original_sequence
                        - pass_number
                        - is_prime
                        - is_reshoot
                        - is_infill
                        - direction
                        - is_incrementing
                        - text
                when:
                    description: |
                        For boolean types, only process this field if the value
                        matches. If `undefined`, the field is processed regardless
                        of the value
                    type: boolean
                    default: undefined
                offset:
                    description: Position in the line name where to insert this field
                    type: number
                    format: integer
                    min: 0
                length:
                    description: Number of characters that this field takes up
                    type: number
                    format: integer
                    min: 1
                value:
                    description: |
                        A default value for this field, or a value to be
                        used in the event of an item of type `text`.
                    type: string
                pad_side:
                    description: |
                        Side to on which to apply padding to the field if
                        the value is shorter than `length`
                    type: string
                    enum:
                        - left
                        - right
                pad_string:
                    description: Character (or string) to use for padding
                    type: string
                    default: " "
                scale_offset:
                    description: |
                        For numeric values, an offset to apply to the value
                        provided by the system. The value is scaled first
                        and then offset
                    type: number
                    default: 0
                scale_multiplier:
                    description: |
                        For numeric values, a multiplier to apply to the
                        value provided by the system. The value is scaled
                        first and then offset.
                    type: number
                    default: 1

        LineNameBuilder:
            description: Line name specification
            type: object
            properties:
                fields:
                    description: List of fields making up the line
                    type: array
                    items:
                        $ref: "#/components/schemas/LineNameBuilderField"


        ASAQCSettings:
            description: Configuration details for making requests to Equinor's ASAQC <abbr title="Application Programming Interface">API</abbr>.
            type: object
            required: [ id, imo, mmsi, subscriptionKey ]
            properties:
                id:
                    type: integer
                    description: The ID for this project in ASAQC. This value must be obtained from Equinor.
                imo:
                    type: integer
                    description: The acquisition vessel's IMO ship identification number.
                mmsi:
                    type: integer
                    description: >
                        The acquisition vessel's current (at the time of acquiring the relevant project)
                        <abbr title="Maritime Mobile Service Identity">MMSI</abbr>.
                subscriptionKey:
                    type: string
                    description: |
                        API subscription key, provided by Equinor, which grants access to the API.

        FilePath:
            description: Filesystem path.
            type: string


        ProjectDefinition:
            type: object
            properties:
                id:
                    type: string
                    description: The project ID. Used throughout the API in the `{project}` path parameter. It must be unique within a Dougal installation.
                name:
                    type: string
                    description: Project name.
                groups:
                    type: array
                    description: A list of *groups* to which the project is assigned. Projects in the same group are expected to share the same, or essentially the same, preplots and acquisition characteristics so that they can be reasonably compared to each other, e.g., for repeatability.
                    items:
                        type: string
                organisations:
                    type: object
                    description: A list of client organisations associated with this project and their level of access
                epsg:
                    type: string
                    description: The EPSG code of the project's CRS, as recognised by PostGIS.
                binning:
                    allOf:
                        - $ref: "#/components/schemas/BinningGridDefinition"
                        - description: The project's binning grid definition.
                archived:
                    type: boolean
                    description: Indicate whether this is an archived project. Archived projects are not scanned for changes.
                    default: false
                preplots:
                    description: |
                        Preplot definitions.

                        <details><summary>Details:</summary>

                        Source and vessel points may be imported from files in standard formats (SPS v1, SPS v2.1, P1/90), in other fixed-width formats, or character-delimited formats (CSV).

                        Additionally, Dougal supports importing ancillary sail line information from especially formatted CSV files.

                        The class of data to be imported is communicated in the `class` attribute and can be one of:

                        - `S` for source points
                        - `V` for vessel points
                        - `saillines` for ancillary sail line information

                        And the file format is given in the `type` attribute, as one of:

                        - `sps`: The legacy value for all fixed-width formats
                        - `fixed-width`: A general purpose fixed-width importer, for files that do not conform to a standard format.
                        - `sps1`: SPS version 1 files.
                        - `sps2.1`: SPS version 2.1 files.
                        - `p190`: P1/90 files.
                        - `p111`: P1/11 files.
                        - `csv`: CSV-formatted files (supports arbitrary delimiters).
                        - `saillines`: A CSV file with a specific format.
                        </details>
                    type: array
                    items:
                        $ref: "#/components/schemas/PreplotFileSpecification"
                online:
                    description: Online data configuration.
                    type: object
                    properties:
                        line:
                            description: Line name details.
                            type: object
                            properties:
                                pattern:
                                    allOf:
                                        - deprecated: true
                                        - $ref: "#/components/schemas/RegExpPatternDefinition"
                                        - description: |
                                            Line name format.

                                            The line details should contain at least the following capture groups:

                                            - `line`: The preplot sailline name.
                                            - `sequence`: The sequence number.

                                            It *may* also contain zero or more of these:

                                            - `direction`: The line direction code (indicates whether the line is being
                                                shot low-to-high or high-to-low).
                                            - `attempt`: The attempt number / code.
                raw:
                    description: Raw data configuration.
                    type: object
                    properties:
                        p111:
                            allOf:
                                - $ref: "#/components/schemas/DataFilePathSpecification"
                                - description: Raw P1/11 file paths and names.
                        p190:
                            allOf:
                                - $ref: "#/components/schemas/DataFilePathSpecification"
                                - description: Raw P1/90 file paths and names **(not well supported – use P1/11 if possible)**.
                        source:
                            description: Energy source data configuration
                            type: object
                            properties:
                                smsrc:
                                    description: Configuration specific to Smartsource gun controllers
                                    type: object
                                    properties:
                                        header:
                                            allOf:
                                                - $ref: "#/components/schemas/DataFilePathSpecification"
                                                - description: |
                                                    Smartsource gun controller header files.

                                                    These files contain sensor information from the guns, such as filling times and pressures, firing delays, system errors, etc.
                                        segy:
                                            allOf:
                                                - $ref: "#/components/schemas/DataFilePathSpecification"
                                                - description: |
                                                    Smartsource SEG-Y files.

                                                    These files contain near field hydrophone data for an entire sequence.
                        ntbp:
                            allOf:
                                - $ref: "#/components/schemas/RegExpPatternDefinition"
                                - description: |
                                    Regular expression used to identify <abbr title="Not To Be Processed">NTBP</abbr>
                                    sequences.

                                    If the (full) path to a raw P1/11 or P1/90 file matches this regular expression,
                                    the sequence is considered to be NTBP and any final data will be ignored.
                planner:
                    $ref: "#/components/schemas/PlannerSettings"
                labels:
                    description: |
                        List of project labels. These labels complement the system's default labels.
                        In the event that a label name matches a system label, the latter gets redefined
                        in the context of this project only.
                    type: array
                    items:
                        $ref: "#/components/schemas/Label"
                events:
                    description: Event settings.
                    type: object
                    properties:
                        presetRemarks:
                            $ref: "#/components/schemas/PresetRemarksList"
                cloud:
                    description: |
                        Cloud API settings.

                        Entries in this section provide information that Dougal needs in order to communicate with remote APIs.
                    type: object
                    properties:
                        asaqc:
                            $ref: "#/components/schemas/ASAQCSettings"




        ProjectSummary:
            type: object
            properties:
                pid:
                    type: string
                    description: The project ID. Used throughout the API in the `{project}` path parameter.
                name:
                    type: string
                    description: Project name.
                schema:
                    type: string
                    description: The internal namespace for a project used by the backend database.
                lines:
                    type: integer
                    description: Number of preplot lines.
                total:
                    type: integer
                    description: Number of preplot points.
                virgin:
                    type: integer
                    description: Number of preplot points that have not been acquired at least once.
                prime:
                    type: integer
                    description: Number of preplot points acquired exactly once.
                other:
                    type: integer
                    description: Number of preplot points acquired more than once (reshoots, overlaps, …)
                ntba:
                    type: integer
                    description: Number of preplot points marked as *NTBA* (Not To Be Acquired). This points do not count towards the total of remaining points.
                remaining:
                    type: integer
                    description: Number of points remaining to be acquired.
                fsp:
                    allOf:
                        - $ref: "#/components/schemas/Shotpoint"
                        - description: First valid shotpoint of the project.
                lsp:
                    allOf:
                        - $ref: "#/components/schemas/Shotpoint"
                        - description: Last final shotpoint acquired so far.
                seq_raw:
                    type: integer
                    description: Number of sequences acquired.
                seq_final:
                    type: integer
                    description: Number of sequences processed.
                prod_duration:
                    allOf:
                        - $ref: "#/components/schemas/Duration"
                        - description: Total production time so far (processed lines only).
                prod_distance:
                    type: number
                    description: Total production distance in metres (processed lines only).
                shooting_rate:
                    type: number
                    description: Average time between shots in production, in seconds.

        PreplotLine:
            type: object
            properties:
                line:
                    type: integer
                    description: Line number.
                fsp:
                    type: integer
                    description: First point number.
                lsp:
                    type: integer
                    description: Last point number.
                num_points:
                    type: integer
                    description: Number of points in this line.
                na:
                    type: integer
                    description: Number of points in this line which have not been acquired and processed at least once (virgin points).
                tba:
                    type: integer
                    description: Number of virgin points in this line which do not have their `ntba` flag set.
                length:
                    type: number
                    description: Length of the line in metres.
                azimuth:
                    type: number
                    description: Grid azimuth of the line, in sexagesimal degrees.
                incr:
                    type: boolean
                    description: "Line direction: `true` if the line is meant to be shot from low to high point numbers, `false` otherwise."
                remarks:
                    type: string
                    description: Arbitrary text entered by the user.
                ntba:
                    type: boolean
                    description: Not to be acquired flag. If `true`, all the points in this line are ignored in production statistics.
                meta:
                    type: object
                    description: Arbitrary JSON data associated with this shotpoint.


        Shotpoint:
            type: object
            properties:
                sequence:
                    type: integer
                    description: Sequence number.
                line:
                    type: integer
                    description: Line number.
                point:
                    type: integer
                    description: Point number.
                objref:
                    type: integer
                    description: P1/11 `objref` value. References the source used during acquisition.
                tstamp:
                    type: string
                    format: date-time
                    description: Acquisition timestamp.
                hash:
                    type: string
                    description: This value uniquely identifies a version of the file from where the shotpoint data was read.
                geometry:
                    allOf:
                        - $ref: "#/components/schemas/GeoJSONPoint"
                        - description: WGS84 position of the shotpoint.
                meta:
                    type: object
                    description: Arbitrary JSON data associated with this shotpoint.

        Sequence:
            type: object
            properties:
                sequence:
                    type: integer
                    description: Sequence number.
                line:
                    type: integer
                    description: Sail line number.
                fsp:
                    type: integer
                    description: First raw data shotpoint.
                lsp:
                    type: integer
                    description: Last raw data shotpoint. May be `null` if the sequence is still being acquired.
                    nullable: true
                fsp_final:
                    type: integer
                    description: First processed data shotpoint. May be `null` if there is no processed data.
                    nullable: true
                lsp_final:
                    type: integer
                    description: Last processed data shotpoint. May be `null` if there is no processed data.
                    nullable: true
                ts0:
                    type: string
                    format: date-time
                    description: Timestamp of the first raw shotpoint.
                ts1:
                    type: string
                    format: date-time
                    description: Timestamp of the last raw shotpoint. May be `null` if the sequence is still being acquired.
                    nullable: true
                ts0_final:
                    type: string
                    format: date-time
                    description: Timestamp of the first processed shotpoint. May be `null` if there is no processed data.
                    nullable: true
                ts1_final:
                    type: string
                    format: date-time
                    description: Timestamp of the last processed shotpoint. May be `null` if there is no processed data.
                    nullable: true
                duration:
                    allOf:
                        - $ref: "#/components/schemas/Duration"
                        - description: Interval between the first and last raw shotpoints.
                duration_final:
                    allOf:
                        - $ref: "#/components/schemas/Duration"
                        - description: Interval between the first and last processed shotpoints.
                num_preplots:
                    type: integer
                    description: Number of points in this sequence having a corresponding preplot.
                num_points:
                    type: integer
                    description: >
                        Total number of points in this sequence. This value is to be interpreted differently depending on the `status` attribute:

                        * `online`: Number of points acquired so far

                        * `raw`: Number of raw shotpoints acquired

                        * `final`: Number of final shotpoints

                        * `ntbp`: This will be either the same as `raw` or `final` depending on whether or not the sequence has been processed. If a sequence has been processed, some or all of the `*_final` attributes will be non-null.
                missing_shots:
                    type: integer
                    description: Number of missing shots. A missing shot is counted as a preplot point that falls between `fsp` and `lsp` and doesn't have a corresponding shotpoint in this sequence.
                length:
                    type: number
                    description: Distance between `fsp_final` and `lsp_final` if both are non-null, otherwise, it's the distance between `fsp` and `lsp`. In metres.
                azimuth:
                    type: number
                    description: Azimuth corresponding to `length`, in sexagesimal degrees.
                remarks:
                    type: string
                    description: Arbitrary user-entered text for the raw sequence data.
                remarks_final:
                    type: string
                    description: Arbitrary user-entered text for the processed sequence data.
                status:
                    type: string
                    enum:
                        - online
                        - raw
                        - final
                        - ntbp
                    description: >
                        Sequence status.

                        * `online`: the sequence is being acquired, or has recently finished but no raw data P1 has been seen yet.

                        * `raw`: the sequence has been acquired but not yet processed.

                        * `final`: a processed P1 corresponding to this sequence has been found and successfully imported.

                        * `ntbp`: the sequence was marked as ‘not to be processed’.

        PlannedSequence:
            type: object
            properties:
                sequence:
                    type: integer
                    description: Planned sequence number.
                line:
                    type: integer
                    description: Preplot line number.
                fsp:
                    type: integer
                    description: First planned shot point.
                lsp:
                    type: integer
                    description: Last planned shot point.
                ts0:
                    type: string
                    format: date-time
                    description: Estimated timestamp of the first shot.
                ts1:
                    type: string
                    format: date-time
                    description: Estimated timestamp of the last shot.
                name:
                    type: string
                    description: Acquisition line name.
                remarks:
                    type: string
                    description: Arbitrary user-entered text.
                meta:
                    type: object
                    description: Arbitrary JSON data associated with this planned sequence.
                duration:
                    allOf:
                        - $ref: "#/components/schemas/Duration"
                        - readOnly: true
                        - description: Interval between `ts0` and `ts1`.
                num_points:
                    type: integer
                    readOnly: true
                    description: Number of shots in the planned sequence.
                length:
                    type: number
                    readOnly: true
                    description: Length of the planned sequence, in metres.
                azimuth:
                    type: number
                    readOnly: true
                    description: Azimuth of the planned sequence.
                class:
                    type: string
                    enum: [ "V" ]
                    readOnly: true
                    description: Planned sequence line type, always `"V"`, meaning this is a sail line.
                geometry:
                    allOf:
                        - $ref: "#/components/schemas/GeoJSONLinestring"
                        - readOnly: true
                        - description: Geometry of the planned line, as a GeoJSON linestring.

        EventNew:
            description: >
                Information of interest for production, processing, QC, reporting or other purposes.

                Events can capture both line related data (line log) referenced by sequence and point,
                or general data (daily log) referenced by timestamp.

                Event entries have a textual description and an optional set of labels to help categorise
                the event, as well as metadata which can include a geographic position for the event.

                A history of event modifications and deletions is kept by the system. In fact, an `Event` object
                is merely an instance of `EventUniqueEdit` which is current at a given point in time.
            type: object
            properties:
                tstamp:
                    type: string
                    format: date-time
                    nullable: true
                    description: Event timestamp.
                sequence:
                    type: number
                    nullable: true
                    description: Event sequence, if applicable.
                point:
                    type: number
                    nullable: true
                    description: Event point, if applicable.
                remarks:
                    type: string
                    description: Event textual remarks.
                labels:
                    type: array
                    items: string
                    description: Labels applied to this event.
                meta:
                    description: Event metadata.
                    type: object
                    properties:
                        geometry:
                            allOf:
                                - $ref: "#/components/schemas/GeoJSONPoint"
                                - description: Event geometry. Typically the location where the event occurred.
                        readonly:
                            type: boolean
                            readOnly: true
                            description: >
                                Flag to indicate that this event is read-only. It cannot be edited by the user or deleted. Typically this concerns system-generated events such as QC results or midnight shots.
                    additionalProperties: true

        EventIDAbstract:
            type: object
            properties:
                id:
                    type: number
                    description: Event ID.


        EventUIDAbstract:
            type: object
            properties:
                uid:
                    type: number
                    description: Event instance unique ID. When an event is modified, the new entry acquires a different `uid` while keeping the same `id` as the original event.


        EventAbstract:
            allOf:
                -
                    $ref: "#/components/schemas/EventIDAbstract"
                -
                    $ref: "#/components/schemas/EventNew"

        Event:
            allOf:
                -
                    $ref: "#/components/schemas/EventAbstract"
                -
                    type: object
                    properties:
                        has_edits:
                            type: boolean
                            description: >
                                Flag to indicate that the event has been edited. The edit history can be retrieved via the relevant endpoint.

        EventUniqueEdit:
            allOf:
                -
                    description: |
                        A unique instance of an event, with information about its time of applicability.

                        For the first instance of an event, the `id` and `uid` are equal. When an edit is made,
                        the `uid` changes while the `id` stays the same. If an event is deleted, the latest
                        `EventUniqueEdit` has its end of validity timestamp set to deletion time. This means that
                        events can be undeleted.
                - $ref: "#/components/schemas/EventAbstract"
                -
                    type: object
                    properties:
                        uid:
                            type: number
                            readOnly: true
                            description: Unique ID of this particular instance of the event. Equals `id` if the event has not been edited.
                        validity:
                            type: array
                            items:
                                type: string
                                format: date-time
                                nullable: true
                            minItems: 4
                            maxItems: 4
                            description: |
                                Temporal validity of this instance of the event. An array where:

                                * The first element if one of `[` or `(` to indicate whether it is an open or closed interval.
                                * The second element is either an ISO-8601 timestamp or `null`. The latter indicates -∞.
                                * The third element is either an ISO-8601 timestamp or `null`. The latter indicates +∞. These are the events returned by endpoints that do not concern themselves with event history.
                                * The fourth element is one of `]` or `)`. As before, it indicates either an open or closed interval.

        EventChangesIsDeletedAbstract:
            type: object
            properties:
                is_deleted:
                    type: boolean
                    description: >
                        Flag to indicate whether this event or event instance (depending on the presence of a `uid` attribute) has been deleted.

        EventChangesIsDeletedTrue:
            allOf:
                -
                    $ref: "#/components/schemas/EventChangesIsDeletedAbstract"
                -
                    type: object
                    properties:
                        is_deleted:
                            const: true

        EventChangesModified:
            description: An event modification.
            allOf:
                -
                    $ref: "#/components/schemas/EventAbstract"
                -
                    $ref: "#/components/schemas/EventChangesIsDeletedAbstract"

        EventChangesDeleted:
            description: |
                Identification of a deleted event or event instance.

                **Note:** the details of the deleted event are not included, only its `id` and `uid`.
            allOf:
                -
                    $ref: "#/components/schemas/EventIDAbstract"
                -
                    $ref: "#/components/schemas/EventUIDAbstract"
                -
                    $ref: "#/components/schemas/EventChangesIsDeletedTrue"

        EventChanges:
            description: List of event changes since the given epoch.
            type: array
            items:
                anyOf:
                    -
                        $ref: "#/components/schemas/EventChangesDeleted"
                    -
                        $ref: "#/components/schemas/EventChangesModified"


        SeisExportEntryFSP:
            type: object
            properties:
                EntryType:
                    type: string
                    enum:
                        - Start of line recording
                    nullable: true
                EntryTypeId:
                    type: integer
                    enum:
                        - 3000
                Comment:
                    type: string
                    nullable: true
                Heading:
                    type: number
                IsReshoot:
                    type: boolean
                IsUndershoot:
                    type: boolean
                LineNumber:
                    type: string
                LineType:
                    type: string
                    enum:
                        - Prime
                        - Infill
                ShotPointId:
                    type: integer
                Time:
                    type: string
                    format: date-time

        SeisExportEntryLSP:
            type: object
            properties:
                EntryType:
                    type: string
                    enum:
                        - End of line recording
                    nullable: true
                EntryTypeId:
                    type: integer
                    enum:
                        - 3007
                Comment:
                    type: string
                    nullable: true
                ShotPointId:
                    type: integer
                Time:
                    type: string
                    format: date-time
                IsNTBP:
                    type: boolean
                LineStatus:
                    type: string
                    enum:
                        - Complete
                        - Incomplete
                        - Pending

        SeisExportEntry:
            type: object
            properties:
                EntryType:
                    type: string
                    enum:
                        - Start good
                        - Start charged
                        - Midnight
                        - End charged
                        - End good
                        - Last good Full Fold
                        - Last charged Full Fold
                        - Start NTBP
                        - End NTBP
                    nullable: true
                EntryTypeId:
                    type: integer
                    enum:
                        - 3001
                        - 3002
                        - 3003
                        - 3005
                        - 3006
                        - 3008
                        - 3009
                        - 3019
                        - 3020
                Comment:
                    type: string
                    nullable: true
                ShotPointId:
                    type: integer
                Time:
                    type: string
                    format: date-time


        SeisExport:
            type: object
            properties:
                DglProjectId:
                    type: string
                Sequences:
                    type: array
                    items:
                        type: object
                        properties:
                            SequenceNumber:
                                type: integer
                            Entries:
                                type: array
                                items:
                                    oneOf:
                                        - $ref: "#/components/schemas/SeisExportEntryFSP"
                                        - $ref: "#/components/schemas/SeisExportEntryLSP"
                                        - $ref: "#/components/schemas/SeisExportEntry"
                            DglNumPoints:
                                type: integer
                            DglNumMissing:
                                type: integer
                            DglLength:
                                type: number


        NavData:
            type: object
            properties:
                _received:
                    type: string
                    format: date-time
                    description: Moment when the data item was received by the Dougal system
                _online:
                    type: boolean
                    description: Whether a line is being acquired
                _latency:
                    type: integer
                    description: If the data item has a timestamp recognisable by Dougal, difference between that timestamp and `_received`
                _sequence:
                    oneOf:
                        - type: string
                        - type: integer
                    description: Sequence number (only present when `_online` is `true`)
                _line:
                    type: integer
                    description: Line number (only present when `_online` is `true`)
                _point:
                    type: integer
                    description: Point number (only present when `_online` is `true`)
                _schema:
                    type: string
                    description: Internal database reference to the current project (only present when `_online` is `true`)


        QueueRequestASAQC:
            description: >
                Parameters of an ASAQC transfer item.
            type: object
            required: [ "project", "sequence", "mimetype" ]
            properties:
                project:
                    type: string
                    description: Project ID.
                sequence:
                    type: integer
                    description: Sequence number.
            example:
                {
                    "project": "eq21205",
                    "sequence": 55
                }


        QueueItem:
            description: Information about an item in the transfers queue
            type: object
            properties:
                item_id:
                    type: integer
                    description: The unique ID of this queue item.
                queue_id:
                    type: integer
                    description: The ID of the queue that this item belongs to.
                status:
                    type: string
                    enum: [ "queued", "cancelled", "failed", "sent" ]
                    description: Status of the queue request. Failed transfers may get rescheduled as a new item, in which case `parent_id` will reference the original request.
                payload:
                    $ref: "#/components/schemas/QueueRequestASAQC"
                results:
                    type: object
                    description: Information about the transfer after an attempt has been made. It is non-empty only for items with status `failed` or `sent`.
                    properties:
                        digest:
                            type: object
                            description: Cryptographic digest of the transmitted payload.
                            properties:
                                sha256:
                                    type: object
                                    description: SHA-256 digest.
                                    properties:
                                        hex:
                                            type: string
                                            description: Hexadecimal representation of the SHA-256 hash of the contents of the file that was sent. Can be used to check, with a high degree of confidence, whether a copy of the file is byte-by-byte the same as the data that was sent.
                        response:
                            type: object
                            description: If the request was successful, the contents of this property are the response body sent by the remote server. If there was an error, the `error` property will be present and may contain details of the problem.
                created_on:
                    type: string
                    format: date-time
                    description: Creation timestamp of this request.
                updated_on:
                    type: string
                    format: date-time
                    description: Last update timestamp of this request.
                not_before:
                    type: string
                    format: date-time
                    description: The request will not be processed before this.
                parent_id:
                    type: integer
                    description: If this request is a retry of a failed attempt, this item references the ID of the original request.
            example:
                {
                    "item_id": 87,
                    "status": "sent",
                    "payload": {
                        "project": "eq21205",
                        "sequence": 55
                    },
                    "results": [
                        {
                            "id": "849e8659-953d-466c-8cfc-ad8d615d1ac0",
                            "fileName": "1065960055S00000-NavLog.json"
                        },
                        {
                            "id": "517864a7-0981-46c6-8f39-aa53da865de7",
                            "fileName": "1065960055S00000-NavLog.pdf"
                        }
                    ],
                    "created_on": "2021-10-03T01:47:02.312Z",
                    "updated_on": "2021-10-03T01:51:19.656Z",
                    "not_before": "1970-01-01T00:00:00.000Z",
                    "parent_id": null
                }

        SoftwareVersion:
            description: Software and component versions
            type: object
            properties:
                name:
                    description: Server application name
                    type: string
                server:
                    description: Server application version
                    type: string
                tag:
                    description: Server application version control tag
                    type: string
                api:
                    description: Application program interface version
                    type: string
                schema:
                    description: Database schema version
                    type: string
                db:
                    description: |
                        Database components.
                        *Only shown to users with write access.*
                    type: object
                    properties:
                        version:
                            description: Database server description
                            type: string
                        postgis_version:
                            description: PostGIS version number
                            type: string
                os:
                    description: |
                        Operating system information. See the [`/etc/os-release` file description](https://www.freedesktop.org/software/systemd/man/latest/os-release.html#Options) for information on the specific values.
                        *Only shown to users with write access.*
                    type: object
                    properties:
                        ID:
                            description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#ID=
                            type: string
                        NAME:
                            description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#NAME=
                            type: string
                        PRETTY_NAME:
                            description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#PRETTY_NAME=
                            type: string
                        VERSION:
                            description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#VERSION=
                            type: string
                        VERSION_ID:
                            description: See https://www.freedesktop.org/software/systemd/man/latest/os-release.html#VERSION_ID=
                            type: string
                compatibility:
                    description: Version compatibility
                    type: array
                    items:
                        type: object
                        description: |
                            Compatibility object. Describes the compatibility requirements of the currently running system.
                        properties:
                            component:
                                description: The component being checked.
                                type: string
                                enum: [ "schema" ]
                            current:
                                description: Current version number for this component.
                                type: string
                            wanted:
                                description: Wanted version. This uses NodeJS' semantic versioning comparisons. See https://github.com/npm/node-semver#ranges for a description of the syntax.
                                type: string
            example:
              {
                "name": "dougal-server-web",
                "server": "0.0.0",
                "tag": "v3-260-g46bb207",
                "api": "0.4.0",
                "schema": "0.4.5",
                "db": {
                  "version": "PostgreSQL 14.8 on x86_64-suse-linux-gnu, compiled by gcc (SUSE Linux) 13.2.1 20230803 [revision cc279d6c64562f05019e1d12d0d825f9391b5553], 64-bit",
                  "postgis_version": "3.3 USE_GEOS=1 USE_PROJ=1 USE_STATS=1"
                },
                "os": {
                  "NAME": "openSUSE Leap",
                  "VERSION": "15.4",
                  "ID": "opensuse-leap",
                  "VERSION_ID": "15.4",
                  "PRETTY_NAME": "openSUSE Leap 15.4"
                },
                "compatibility": [
                  {
                    "current": "0.4.5",
                    "wanted": "^0.4.5",
                    "component": "schema"
                  },
                  {
                    "current": "0.4.0",
                    "wanted": "^0.4.0",
                    "component": "api"
                  }
                ]
              }


        ServerDiagnostics:
            description: Server diagnostics information
            type: object
            properties:
                hostname:
                    description: Returns the host name of the operating system as a string
                    type: string
                memory:
                    description: Returns system memory information
                    type: object
                    properties:
                        total:
                            description: Returns the total amount of system memory in bytes as an integer.
                            type: number
                        free:
                            description: Returns the amount of free system memory in bytes as an integer.
                            type: number
                uptime:
                    description: Returns the system uptime in number of seconds.
                    type: number
                loadavg:
                    description: |
                        Returns an array containing the 1, 5, and 15 minute load averages.
                        The load average is a measure of system activity calculated by the operating system and expressed as a fractional number.
                    type: array
                    items:
                        type: number
                    minItems: 3
                    maxItems: 3
                networkInterfaces:
                    description: |
                        Returns an object containing network interfaces that have been assigned a network address.
                        Each key on the returned object identifies a network interface. The associated value is an array of objects that each describe an assigned network address.
                    type: object
                    additionalProperties:
                        description: Interface name
                        type: array
                        items:
                            type: object
                            properties:
                                address:
                                    description: The assigned IPv4 or IPv6 address
                                    type: string
                                netmask:
                                    description: The IPv4 or IPv6 network mask
                                    type: string
                                family:
                                    description: Either `IPv4` or `IPv6`
                                    type: string
                                mac:
                                    description: The MAC address of the network interface
                                    type: string
                                internal:
                                    description: |
                                        `true` if the network interface is a loopback or similar interface that is not remotely accessible; otherwise `false`
                                    type: boolean
                                cidr:
                                    description: The assigned IPv4 or IPv6 address with the routing prefix in CIDR notation. If the `netmask` is invalid, this property is set to `null`.
                                    type: string
                                scopeid:
                                    description: The numeric IPv6 scope ID (only specified when `family` is `IPv6`)
                                    type: integer
                cpus:
                    description: Returns an array of objects containing information about each logical CPU core.
                    type: array
                    items:
                        description:
                        type: object
                        properties:
                            model:
                                description: CPU model string
                                type: string
                            speed:
                                description: Current speed in MHz
                                type: integer
                            times:
                                description: CPU usage information
                                type: object
                                properties:
                                    user:
                                        description: The number of milliseconds the CPU has spent in user mode.
                                        type: integer
                                    nice:
                                        description: The number of milliseconds the CPU has spent in nice mode.
                                        type: integer
                                    sys:
                                        description: The number of milliseconds the CPU has spent in sys mode.
                                        type: integer
                                    idle:
                                        description: The number of milliseconds the CPU has spent in idle mode.
                                        type: integer
                                    irq:
                                        description: The number of milliseconds the CPU has spent in irq mode.
                                        type: integer
                storage:
                    description: Returns information about filesystems and storage usage
                    type: object
                    properties:
                        root:
                            description: Provides information about the root file system.
                            type: object
                            properties:
                                total:
                                    description: Total number of bytes
                                    type: integer
                                free:
                                    description: Free space (in bytes)
                                    type: integer
                                available:
                                    description: Space available to the Dougal user (in bytes)
                                    type: integer
                                used:
                                    description: Used space (in bytes)
                                    type: integer
                                usedPercent:
                                    description: |
                                        `free` / `available` * 100
                                    type: number
                        data:
                            description: Return storage information for each data path accessible to Dougal users via the API
                            type: object
                            additionalProperties:
                                description: The property name is the name the user sees for this subpath.
                                type: object
                                properties:
                                    total:
                                        description: Total number of bytes
                                        type: integer
                                    free:
                                        description: Free space (in bytes)
                                        type: integer
                                    available:
                                        description: Space available to the Dougal user (in bytes)
                                        type: integer
                                    used:
                                        description: Used space (in bytes)
                                        type: integer
                                    usedPercent:
                                        description: |
                                            `free` / `available` * 100
                                        type: number
                database:
                    description: Returns database space usage information
                    type: object
                    properties:
                        size:
                            description: Total size of the PostgreSQL database (in bytes)
                            type: integer
                        projects:
                            description: Individual project information
                            type: object
                            additionalProperties:
                                description: Information about each project. The property name is the project's ID.
                                type: object
                                properties:
                                    size:
                                        description: Size of the storage used by this project (in bytes)
                                        type: integer
                                    percent:
                                        description: Size as a percentage of the entire PostgreSQL used storage
                                        type: number
            example:
                {
                "hostname": "dougal04",
                "memory": {
                    "total": 16324186112,
                    "free": 14940069888
                },
                "uptime": 955504.5,
                "loadavg": [
                    0.49,
                    0.49,
                    0.69
                ],
                "networkInterfaces": {
                    "lo": [
                    {
                        "address": "127.0.0.1",
                        "netmask": "255.0.0.0",
                        "family": "IPv4",
                        "mac": "00:00:00:00:00:00",
                        "internal": true,
                        "cidr": "127.0.0.1/8"
                    },
                    {
                        "address": "::1",
                        "netmask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
                        "family": "IPv6",
                        "mac": "00:00:00:00:00:00",
                        "internal": true,
                        "cidr": "::1/128",
                        "scopeid": 0
                    }
                    ],
                    "em1": [
                    {
                        "address": "172.31.135.140",
                        "netmask": "255.255.255.0",
                        "family": "IPv4",
                        "mac": "b8:cb:29:dd:c2:1e",
                        "internal": false,
                        "cidr": "172.31.135.140/24"
                    },
                    {
                        "address": "fe80::bacb:29ff:fedd:c21e",
                        "netmask": "ffff:ffff:ffff:ffff::",
                        "family": "IPv6",
                        "mac": "b8:cb:29:dd:c2:1e",
                        "internal": false,
                        "cidr": "fe80::bacb:29ff:fedd:c21e/64",
                        "scopeid": 2
                    }
                    ],
                    "em2": [
                    {
                        "address": "172.31.135.12",
                        "netmask": "255.255.255.0",
                        "family": "IPv4",
                        "mac": "b8:cb:29:dd:c2:1f",
                        "internal": false,
                        "cidr": "172.31.135.12/24"
                    },
                    {
                        "address": "fe80::bacb:29ff:fedd:c21f",
                        "netmask": "ffff:ffff:ffff:ffff::",
                        "family": "IPv6",
                        "mac": "b8:cb:29:dd:c2:1f",
                        "internal": false,
                        "cidr": "fe80::bacb:29ff:fedd:c21f/64",
                        "scopeid": 3
                    }
                    ]
                },
                "cpus": [
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 65874900,
                        "nice": 37340,
                        "sys": 6784430,
                        "idle": 877795820,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 59011560,
                        "nice": 45110,
                        "sys": 6114070,
                        "idle": 886504400,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 52777060,
                        "nice": 59160,
                        "sys": 5497730,
                        "idle": 893863890,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 2292,
                    "times": {
                        "user": 49464660,
                        "nice": 820,
                        "sys": 5265370,
                        "idle": 897610020,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 47904520,
                        "nice": 9410,
                        "sys": 5337240,
                        "idle": 899077360,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 40433680,
                        "nice": 54890,
                        "sys": 4350020,
                        "idle": 906785860,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 24040170,
                        "nice": 17370,
                        "sys": 3533740,
                        "idle": 924358390,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 32668650,
                        "nice": 39340,
                        "sys": 4629000,
                        "idle": 915014220,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 39244360,
                        "nice": 9000,
                        "sys": 5110890,
                        "idle": 908206780,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 42595880,
                        "nice": 14420,
                        "sys": 5186740,
                        "idle": 904591700,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 44487620,
                        "nice": 43310,
                        "sys": 5266430,
                        "idle": 902752740,
                        "irq": 0
                    }
                    },
                    {
                    "model": "Intel(R) Xeon(R) E-2236 CPU @ 3.40GHz",
                    "speed": 3400,
                    "times": {
                        "user": 49013200,
                        "nice": 89360,
                        "sys": 5229000,
                        "idle": 896654340,
                        "irq": 0
                    }
                    }
                ],
                "storage": {
                    "root": {
                    "total": 981132492800,
                    "free": 955562377216,
                    "available": 905648078848,
                    "used": 25570115584,
                    "usedPercent": 2.6061837490497184
                    },
                    "data": {
                    "Nav": {
                        "total": 2199023255552,
                        "free": 1895510478848,
                        "available": 1895510478848,
                        "used": 303512776704,
                        "usedPercent": 13.802163116633892
                    },
                    "Mech": {
                        "total": 1099511627776,
                        "free": 641156898816,
                        "available": 641156898816,
                        "used": 458354728960,
                        "usedPercent": 41.687119752168655
                    },
                    "Client": {
                        "total": 1099511627776,
                        "free": 1062877327360,
                        "available": 1062877327360,
                        "used": 36634300416,
                        "usedPercent": 3.331870213150978
                    },
                    "Backup": {
                        "total": 4398046511104,
                        "free": 3328588230656,
                        "available": 3328588230656,
                        "used": 1069458280448,
                        "usedPercent": 24.31666599586606
                    }
                    }
                },
                "database": {
                    "size": 8437662499,
                    "projects": {
                    "eq21200": {
                        "size": 442359808,
                        "percent": 5.242681940080287
                    },
                    "eq22200": {
                        "size": 174219264,
                        "percent": 2.064781140756078
                    },
                    "eq22205": {
                        "size": 140255232,
                        "percent": 1.6622522175617065
                    },
                    "eq23200": {
                        "size": 185573376,
                        "percent": 2.199345802489652
                    },
                    "eq23205": {
                        "size": 319479808,
                        "percent": 3.786354432141171
                    },
                    "eq24200": {
                        "size": 161128448,
                        "percent": 1.9096337169102975
                    }
                    }
                }
                }

        AbstractOrganisationAccess:
            description: Access rights for a given organisation. The property name is used as the organisation's name.
            type: object
            properties:
                read:
                    type: boolean
                    description: Users belonging to this organisation can view / read data from projects which grant `read` access to the organisation's members
                write:
                    type: boolean
                    description: Users belonging to this organisation can add, change or write data from projects which grant `write` access to the organisation's members
                edit:
                    type: boolean
                    description: Users belonging to this organisation can manage (e.g., change settings of) projects which grant `edit` access to the organisation's members
            additionalProperties:
                type: boolean
                description: Other operations (e.g., `delete`, `move`, `create`) may be listed here if the need arises
            propertyNames:
                pattern: "^[a-z][a-z_0-9]+$"

        SimpleUser:
            description: A user with defined access rights over projects
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                    readOnly: true
                    description: A unique ID for the user, generated by the system
                name:
                    type: string
                    description: A short name for the user. Note that the name does not have to be unique!
                email:
                    type: string
                    format: email
                    description: An optional email address for this user.
                colour:
                    type: string
                    description: A colour, in hex form or as a named colour supported by Vuetify, to assist the user with visual self-identification in the user interface.
                active:
                    type: boolean
                    description: Whether the user is active or not. Inactive users are not able to log in.
                organisations:
                    type: object
                    description: A list of organisations that the user has access to, and the permitted actions (read, write, edit, etc.)
                    additionalProperties:
                        $ref: "#/components/schemas/AbstractOrganisationAccess"

        NamedUser:
            allOf:
                - $ref: "#/components/schemas/SimpleUser"
                - description: A user identified by a user name and password
                - type: object
                - properties:
                    hash:
                        type: string
                        writeOnly: true
                        description: A hash of the user's password

        NamedUserSelfEditable:
            description: |
                Payload of an edit request of a `NamedUser` made by the user himself.
                Any other attributes will be ignored.
            type: object
            properties:
                email:
                    type: string
                    format: email
                    description: An optional email address for this user.
                colour:
                    type: string
                    description: A colour, in hex form or as a named colour supported by Vuetify, to assist the user with visual self-identification in the user interface.
                password:
                    type: string
                    writeOnly: true
                    description: A new password for the user


        CertificateUser:
            allOf:
                - $ref: "#/components/schemas/SimpleUser"
                - description: A user identified by a TLS client certificate
                - type: object
                - properties:
                    public_key:
                        type: string
                        description: The user's public key, ASCII armoured


        HostUser:
            allOf:
                - $ref: "#/components/schemas/SimpleUser"
                - description: A user identified by a hostname
                - type: object
                - properties:
                    host:
                        type: string
                        description: >
                            Hostname of the client attempting to connect. If matched, the user will be logged in automatically.

        IPUser:
            allOf:
                - $ref: "#/components/schemas/SimpleUser"
                - description: A user identified by an IP address. Only IPv4 is supported at this time.
                - type: object
                - properties:
                    ip:
                        type: string
                        description: |
                            IP address or subnet of the client attempting to connect. If matched, the user will be logged in automatically.

                            For instance, this will log in as the user `user1` anyone connecting from `192.168.1.10`:

                            ```yaml
                            ip: 192.168.1.10
                            name: user1
                            ```

                            And this will log in as `guest` anyone on the 192.168.1.0/24 subnet:

                            ```yaml
                            ip: 192.168.1.0/24
                            name: guest
                            ```

                            More specific address take precedence over less specific ones.

        User:
            allOf:
                - summary: A user of the system
                - description: |
                    Each user has a `name`, a `colour` (used for display purposes and ease of self-identification), an `active` flag (whether the user can log in or not) and a list of `organisations` that the user belongs to.

                    On top of that, there are different kinds of users depending on the method used to identify them. Users may be identified, in order of priority:

                    * By a TLS client certificate that is presented to the server by their browser
                    * By a password that they use to log in with
                    * By the IP address of their client machine
                    * By the host name of their client machine

                - oneOf:
                    - $ref: "#/components/schemas/NamedUser"
                    - $ref: "#/components/schemas/CertificateUser"
                    - $ref: "#/components/schemas/HostUser"
                    - $ref: "#/components/schemas/IPUser"


        UserValidationRequest:
            summary: User validation request
            description: A request for the user to validate an action on his profile
            type: object
            properties:
                id:
                    type: string
                    format: UUID
                    summary: Validation ID
                    description: This is the ID of the validation object in the database
                # user:
                    # $ref: "#/components/schemas/NamedUser"
                validate:
                    type: string
                    enum: [ "create", "email", "password" ]
                    description: |
                        The type of validation to be performed:

                        * `create`: The user entry has been created. The system requires the response to include a password.
                        * `email`: The user's email address has been changed (or added). The system expects the user to confirm that the new email address is valid.
                        * `password`: The user has forgotten his password. The system requires the response to include a new password.


        UserValidationResponsePassword:
            type: object
            description: Creation confirmation or password change
            properties:
                id:
                    type: string
                    format: UUID
                    description: Validation ID
                password:
                    type: string
                    description: New user password


        UserValidationResponseEmail:
            type: object
            description: Change of email
            properties:
                id:
                    type: string
                    format: UUID
                    description: Validation ID
                email:
                    type: string
                    format: email
                    description: New email address


        UserValidationResponse:
            oneOf:
                - $ref: "#/components/schemas/UserValidationResponsePassword"
                - $ref: "#/components/schemas/UserValidationResponseEmail"


        # UserRole:
        #     description:
        #
        # User:
        #     description: Information about a user
        #     type: object
        #     properties:
        #         name:
        #             type: string
        #             description: A user name. Must be unique within a Dougal installation.
        #         role:
        #             $ref: "#/components/schemas/UserRole"



security:
    - BearerAuthUser: []
    - CookieAuthUser: []

paths:

    /config/label:
        get:
            summary: List label definitions
            description: |
                Get a list of all labels defined in this system.
                Note that unlike the [project-level labels endpoint](#tag/project/paths/~1project~1{project}~1label/get),
                only admins may query system-wide labels.
            tags: [ "configuration" ]
            security:
                # TODO
                # Only users with `{"*": {read: true}}` access can query
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            responses:
                "200":
                    description: Label definitions
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Label"
                "401":
                    $ref: "#/components/responses/401"

        post:
            summary: Create one or more labels
            description: |
                This endpoint accepts both JSON and YAML payloads consisting of either a single label object
                or an array of label objects.
            tags: [ "configuration" ]
            security:
                # TODO
                # Only users with `{"*": {edit: true}}` access are authorised
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            oneOf:
                                - $ref: "#/components/schemas/Label"
                                -
                                    title: List of Label
                                    type: array
                                    items:
                                        $ref: "#/components/schemas/Label"
                    application/yaml:
                        schema:
                            oneOf:
                                - $ref: "#/components/schemas/Label"
                                -
                                    title: List of Label
                                    type: array
                                    items:
                                        $ref: "#/components/schemas/Label"
            responses:
                "201":
                    description: A new label or set of labels has been created
                "400":
                    $ref: "#/components/responses/400"
                "401":
                    $ref: "#/components/responses/401"
                "409":
                    description: |
                        The value used for the `name` property conflicts with an existing label.
                        If creating multiple labels, this error is returned if *any* of them matches
                        an existing label name – in that case, none of the labels in the set will be
                        created.

    /config/label/{name}:
        get:
            summary: Get label definition
            description: |
                Note that unlike the [project-level labels endpoint](#tag/project/paths/~1project~1{project}~1label/get),
                only admins may query system-wide labels.
            tags: [ "configuration" ]
            security:
                # TODO
                # Only users with `{"*": {read: true}}` access are authorised
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            responses:
                "200":
                    description: Label definitions
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Label"
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    $ref: "#/components/responses/404"

        put:
            summary: Modify an existing label
            description: |
                Note that this endpoint may be *not* be used to rename an existing label. The `name` attribute is
                expected to match the `name` parameter; if those values don't match, the request will fail with a
                400 error.
            tags: [ "configuration" ]
            security:
                # TODO
                # Only users with `{"*": {edit: true}}` access are authorised
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            parameters:
                -
                    name:
                        in: path
                        description: Label name.
                        schema:
                            type: string
                        required: true
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/Label"
            responses:
                "201":
                    description: The label has been updated
                "400":
                    $ref: "#/components/responses/400"
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    $ref: "#/components/responses/404"

        delete:
            summary: Delete a label
            tags: [ "configuration" ]
            security:
                # TODO
                # Only users with `{"*": {edit: true}}` access are authorised
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            parameters:
                -
                    name:
                        in: path
                        description: Label name.
                        schema:
                            type: string
                        required: true
            responses:
                "204":
                    description: The label no longer exists (or has never existed)
                "401":
                    $ref: "#/components/responses/401"

    /project:
        get:
            description: Get list of projects.
            tags: [ "project" ]
            security:
                # TODO
                # Only users with:
                # `{"*": {read: true}}`
                # can access all projects
                # Other users can only access projects for which they have a
                # `{":project": {read: true}}`
                # claim.
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            responses:
                "200":
                    description: List of projects
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    type: object
                                    properties:
                                        pid:
                                            type: string
                                            description: The project ID. Used throughout the API in the `{project}` path parameter.
                                        name:
                                            type: string
                                            description: Project name
                                        schema:
                                            type: string
                                            description: The internal namespace for a project used by the backend database.
                                        groups:
                                            type: array
                                            items:
                                                type: string
                                            description: Zero or more strings, each representing a *group name*. These are used to group together related projects with the same or similar preplots in order to do temporal comparisons and statistics.
                "401":
                    $ref: "#/components/responses/401"

        post:
            summary: Create a project
            description: >
                When creating a project, the `id` property must not already exist in this Dougal installation.

                Note that this endpoint accepts both JSON and YAML payloads.

                **Security:**

                * The user must have `edit` access on at least one organisation.
                * The user will only be able to assign projects to organisations they have `edit` access to.
            tags: [ "project", "configuration" ]
            security:
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "#/components/schemas/ProjectDefinition"
                                - required:
                                    - id
                                    - name
                                    - epsg
                                    - binning
                    application/yaml:
                        schema:
                            allOf:
                                - $ref: "#/components/schemas/ProjectDefinition"
                                - required:
                                    - id
                                    - name
                                    - epsg
                                    - binning
            responses:
                "201":
                    description: The new project has been created
                "400":
                    $ref: "#/components/responses/400"
                "401":
                    $ref: "#/components/responses/401"
                "409":
                    description: The value used for the `id` property conflicts with an existing project.

    /project/{project}/configuration:
        get:
            summary: Get a project's configuration
            description: |
                **Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.

                **TODO:** Users with just `read` or `write` authorisation might need to get access to at least part of the configuration too.
            tags: [ "project", "configuration" ]
            security:
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            parameters:
                - $ref: "#/components/parameters/ETag"
                - $ref: "#/components/parameters/CSVDelimiter"
            responses:
                "200":
                    description: Project configuration data.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                        application/yaml:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                        text/csv:
                            schema:
                                type: string
                                contentMediaType: text/csv
                                description: |
                                    A CSV representation of the project configuration, with the following columns:

                                    * `key`: Configuration value key.
                                    * `value`: Configuration value entry.

                                    The actual configuration object is ‘flattened’ by creating unique keys for nested values, consisting of the nested property names concatenated together with a `.` separator.
                            example: |
                                key,value
                                id,EQ23206
                                qc.parameters,/QC Defaults/parameters.yaml
                                qc.definitions,/QC Defaults/definitions.yaml
                                raw.ntbp.pattern.flags,i
                                raw.ntbp.pattern.regex,NTBP
                                raw.p111.globs.0,**/*.P111
                                raw.p111.globs.1,**/*.p111
                                raw.p111.paths.0,/Projects/2023/Grane EQ23206/01 Sequences Raw Files
                                raw.p111.pattern.flags,i
                                raw.p111.pattern.regex,^.*(10|20)([0-9]{4})([0-9])([0-9]{3})S00000\.([0-9]+)\.[Pp]?111$
                                raw.p111.pattern.captures.0,direction
                                raw.p111.pattern.captures.1,line
                                raw.p111.pattern.captures.2,attempt
                                raw.p111.pattern.captures.3,sequence
                                raw.p111.pattern.captures.4,file_no


        put:
            summary: Update a project's configuration.
            description: >
                The `id` property in the payload *must* match the `project` URL parameter.

                **Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.
            tags: [ "project", "configuration" ]
            security:
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/If-Match"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "#/components/schemas/ProjectDefinition"
                                - required:
                                    - id
                                    - name
                                    - epsg
                                    - binning
                    application/yaml:
                        schema:
                            allOf:
                                - $ref: "#/components/schemas/ProjectDefinition"
                                - required:
                                    - id
                                    - name
                                    - epsg
                                    - binning
            responses:
                "200":
                    description: Project configuration data.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                        application/yaml:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                "400":
                    description: There was a problem with the syntax or the data of the request
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    $ref: "#/components/responses/404"
                "409":
                    description: The value used for the `id` property conflicts with an existing project.
                "412":
                    $ref: "#/components/responses/412"
                "428":
                    $ref: "#/components/responses/428"

        patch:
            summary: Partial project configuration update.
            description: |
                This endpoint is used to update part of a project configuration.
                Partial representations may be provided, in which case, only the keys provided in the payload will be updated.

                Keys referencing an object cause the payload to be merged into the existing object, arbitrarily deep. Other values (strings, arrays, numbers, etc.) are replaced instead.

                If a key has a value of **null**, the key will be removed from the object.

                **Security:** The user must have `edit` access to at least one of the organisations that the project gives `edit` access to.
            tags: [ "project", "configuration" ]
            security:
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/If-Match"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/ProjectDefinition"
                        example:
                            { "archived": true }
                    application/yaml:
                        schema:
                            $ref: "#/components/schemas/ProjectDefinition"
                        example: |
                            # Update the planner configuration details
                            # Recall that a complete representation of
                            # the `planner` object must be provided,
                            # even if only one of the values has changed.
                            planner:
                                defaultLineChangeDuration: 60 # One hour
                                defaultAcquisitionSpeed: 4.5 # Knots
                                overlapBefore: 16
                                overlapAfter: 16

            responses:
                "200":
                    description: >
                        A complete representation of the project configuration data, including
                        any changes applied by this request.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                        application/yaml:
                            schema:
                                $ref: "#/components/schemas/ProjectDefinition"
                "400":
                    description: There was a problem with the syntax or the data of the request
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    $ref: "#/components/responses/404"
                "409":
                    description: The value used for the `id` property conflicts with an existing project.
                "412":
                    $ref: "#/components/responses/412"
                "428":
                    $ref: "#/components/responses/428"



    /project/{project}:
        # Synonym: /project/{project}/summary:
        get:
            summary: Get details about a specific project.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "project" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: Summary of project status and details.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ProjectSummary"
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/line/:
        get:
            summary: Get list of preplot lines.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "preplot" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: List of preplot lines.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/PreplotLine"
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/line/{line}:
        patch:
            summary: Update preplot line information.
            description: |
                All of the properties are optional. Users may specify only the one(s) they need, other properties remain unchanged. An empty object body causes the resource not to be modified at all.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "preplot" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Line"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                remarks:
                                    type: string
                                    description: Overwrite the remarks text
                                meta:
                                    type: object
                                    description: Overwrite the `meta` object with a new one.
                                ntba:
                                    type: boolean
                                    description: Set the ‘Not To Be Processed’ flag to `true` or `false`.
                                complete:
                                    type: boolean
                                    description: If `true`, set the ‘Not To Be Processed’ flag to `true` on any points in the line which have not yet been successfully acquired and processed at least once (virgin points). If `false`, set the NTBA flag to `false` on *all* points in this line.

            responses:
                "204":
                    description: The resource has been successfully updated.


    /project/{project}/sequence/:
        get:
            summary: Get list of sequences.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "sequences" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: List of sequences.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Sequence"
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/sequence/{sequence}:
        get:
            summary: Get a sequence
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "sequences" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Sequence"
            responses:
                "200":
                    description: Sequence data.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Sequence"
                        application/vnd.seis+json:
                            schema:
                                type: object
                        application/geo+json:
                            schema:
                                $ref: "#/components/schemas/GeoJSONFeature"
                        text/html:
                            schema:
                                type: string
                        application/pdf:
                            schema:
                                type: string
                                format: binary
        patch:
            summary: Update sequence information.
            description: |
                All of the properties are optional. Users may specify only the one(s) they need, other properties remain unchanged. An empty object body causes the resource not to be modified at all. Final sequence properties only have effect if a final P1 file exists for the relevant sequence.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.

            tags: [ "sequences" ]
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Sequence"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                remarks:
                                    type: string
                                    description: Overwrite the remarks text for the raw sequence
                                remarks_final:
                                    type: string
                                    description: Overwrite the remarks text for the final sequence, if it exists
                                meta:
                                    description: Overwrite the `meta` object for the raw sequence
                                    type: object
                                meta_final:
                                    type: object
                                    description: Overwrite the `meta` object for the final sequence, if it exists
            responses:
                "204":
                    description: The resource has been successfully updated.
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/sequence/{sequence}/{shot}:
        get:
            summary: Retrieve shotpoint information
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "sequences" ]
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Sequence"
                - $ref: "#/components/parameters/Shotpoint"
                - $ref: "#/components/parameters/QueryProject"
                -
                    description: Source of shotpoint data.
                    name: kind
                    in: query
                    schema:
                        type: string
                        enum: [ raw, final ]
                        default: raw
            responses:
                "200":
                    description: Shotpoint data
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Shotpoint"
                        application/geo+json:
                            schema:
                                $ref: "#/components/schemas/GeoJSONFeature"
                "404":
                    description: |
                        The requested shotpoint does not exist.

                        If used with `kind=final`, a **404** will be returned if the sequence has not yet been processed.
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/plan:
        get:
            summary: Get list of planned sequences.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "planner" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: List of planned sequences.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    remarks:
                                        type: string
                                        description: Planner remarks
                                    sequences:
                                        type: array
                                        items:
                                            $ref: "#/components/schemas/PlannedSequence"
                        text/csv:
                            schema:
                                type: string
                                format: csv
                                description: |
                                    Returns a CSV response containing one row for each planned sequence, with the following columns:

                                    * `sequence`: Sequence number
                                    * `line`: Line number
                                    * `fsp`: First shotpoint
                                    * `lsp`: Last shotpoint
                                    * `ts0`: Estimated timestamp of the first shotpoint
                                    * `ts1`: Estimated timestamp of the last shotpoint
                                    * `name`: Line name
                                    * `remarks`: Arbitrary comments
                                    * `num_points`: Number of shotpoints
                                    * `duration`: Estimated duration in seconds
                                    * `length`: Line length in metres
                                    * `azimuth`: Line azimuth
                                    * `lon0`: Longitude of the first shotpoint
                                    * `lat0`: Latitude of the first shotpoint
                                    * `lon1` Longitude of the last shotpoint
                                    * `lat1`: Latitude of the last shotpoint
                            example: |
                                "sequence","line","fsp","lsp","ts0","ts1","name","remarks","num_points","duration","length","azimuth","lon0","lat0","lon1","lat1"
                                81,5162,2422,1158,"2023-10-22T11:09:24.912Z","2023-10-22T12:56:03.395Z","2051621081S00000","",633,6398,15799.988472147348,26.4703415983101,2.474872,59.086695,2.596266,59.214146
                                82,5178,2444,1146,"2023-10-22T12:56:03.000Z","2023-10-22T14:45:33.607Z","2051781082S00000","",650,6570,16225.02094944685,26.470137885560813,2.469632,59.085264,2.594277,59.216147
                        text/html:
                            schema:
                                type: string
                                format: html
                                description: |
                                    An HTML representation of the plan.
                        application/pdf:
                            schema:
                                type: string
                                contentMediaType: application/pdf
                                description: |
                                    A PDF representation of the plan.


        post:
            summary: Add a new sequence to the plan.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "planner" ]
            parameters:
                - $ref: "#/components/parameters/Project"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PlannedSequence"
            responses:
                "201":
                    description: Sequence successfully added
                "401":
                    $ref: "#/components/responses/401"

        put:
            summary: Modify a planned sequence
            description: |
                Note that the `line` property cannot be modified and if supplied it will be silently ignored. To change the line, delete the sequence and create a new one. To change the sequence number, use a `PATCH` request instead.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "planner" ]
            parameters:
                - $ref: "#/components/parameters/Project"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PlannedSequence"
            responses:
                "201":
                    description: Sequence successfully modified
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/plan/{sequence}:
        patch:
            summary: Modify a planned sequence
            description: |
                By using this endpoint it is possible to change the sequence number by providing the new value in the `sequence` property of the request body. On the other hand, the `line` property cannot be modified.

                Note that only those attributes that are to be modified are required to be supplied in the request body.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "planner" ]
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Sequence"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PlannedSequence"
            responses:
                "201":
                    description: Sequence successfully modified
                "401":
                    $ref: "#/components/responses/401"

        delete:
            summary: Remove a sequence from the plan.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "planner" ]
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Sequence"
            responses:
                "204":
                    description: Returned when the sequence no longer exists in the plan. Note that it is possible that the sequence never existed in the first place, as supplying a valid but non-existing sequence number is not an error.
                "401":
                    $ref: "#/components/responses/401"


#     /project/{project}/linename:
#         post:
#             summary: Get a line name based on the supplied data
#             tags: [ "planner" ]
#             security:
#                 - BearerAuthGuest: []
#                 - CookieAuthGuest: []
#             requestBody:
#                 required: true
#                 content:
#                     application/json:
#                         schema:
#
#             responses:
#                 "200":
#                     description: Available line name items
#                     content:
#                         application/json:
#                             schema:
#                                 $ref: "#/components/schemas/LineNameProperties"



    /project/{project}/linename/properties:
        get:
            summary: Get available line name components
            description: |
                This endpoint returns a description of the available items that
                may be used to construct a line name, such as line number, sequence,
                etc.

                **Security:** As this endpoint is only ever called by those editing the configuration,
                `edit` authorisation on at least one organisation can be required. Alternatively, it
                can just be left open to everyone. (TODO)
            tags: [ "planner" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            responses:
                "200":
                    description: Available line name items
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/LineNameProperties"

    /project/{project}/event:
        get:
            summary: Get project events.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "log" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/CSVDelimiter"
                - $ref: "#/components/parameters/CSVFields"
                - $ref: "#/components/parameters/CSVHeader"
                - $ref: "#/components/parameters/QueryMime"
                - $ref: "#/components/parameters/QueryFilename"
            responses:
                "200":
                    description: List of project events
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Event"

                        application/geo+json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/GeoJSONFeature"

                        application/vnd.seis+json:
                            schema:
                                $ref: "#/components/schemas/SeisExport"

                        application/yaml:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Event"
                            example: |
                                - id: 12042
                                tstamp: 2023-10-15T12:43:16.000Z
                                sequence: null
                                point: null
                                remarks: New event 5
                                labels: []
                                meta: {}
                                has_edits: true
                                modified_on: 2023-10-17T08:51:51.069Z
                                - id: 11727
                                tstamp: 2023-10-05T06:02:54.664Z
                                sequence: 80
                                point: 2364
                                remarks: LGSP 2051220080S00000
                                labels:
                                    - LGSP
                                meta:
                                    auto:
                                    LGSP: final_line
                                has_edits: false
                                modified_on: 2023-10-14T19:50:08.429Z
                                - id: 11728
                                tstamp: 2023-10-05T06:02:54.664Z
                                sequence: 80
                                point: 2364
                                remarks: LSP 2051220080S00000
                                labels:
                                    - LSP
                                meta:
                                    auto:
                                    LSP: final_line
                                has_edits: false
                                modified_on: 2023-10-14T19:50:08.429Z


                        text/csv:
                            schema:
                                type: string
                                contentMediaType: text/csv
                                description: |
                                    A CSV representation of the event log, with the following columns:

                                    * `timestamp`: Event timestamp, in UTC.
                                    * `sequence`: Sequence number, if applicable.
                                    * `point`: Point number, if applicable.
                                    * `text`: Event text. May contain newlines and [Markdown](https://daringfireball.net/projects/markdown/syntax "Markdown syntax"). formatting.
                                    * `labels`: Labels associated with the event. Multiple labels are separated by `;` *(be careful about using `;` as a field separator!)*
                                    * `latitude`: Event latitude, if the event has a Point geometry.
                                    * `longitude`: Event longitude, if the event has a Point geometry.
                                    * `id`: Event ID internal to Dougal.

                "401":
                    $ref: "#/components/responses/401"
        post:
            summary: Add a new event
            description: |
                Creates a new event in the database.

                Either `tstamp` or *both of* `sequence` and `point` must be present. It is also acceptable to provide all three, but the system *will not check for consistency.*

                If `tstamp` is missing the system will try to populate it from the shots table, but that may not happen immediately.

                It is possible to add an event for a sequence or shot which does not (yet) exist. If the shot eventually comes into existence the timestamp will be populated accordingly.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "log" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EventNew"
            responses:
                "201":
                    description: New event created successfully
                "401":
                    $ref: "#/components/responses/401"

    /project/{project}/event/{id}:
        get:
            summary: Retrieve event history.
            description: |
                Get all the history for an event.

                When an event is modified, a new instance is created and saved in the database along with the modification timestamps. Similarly, when an event is deleted its latest instance is merely marked with an end of validity time, causing it to no longer appear in the event lists.

                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "log" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/EventID"
            responses:
                "200":
                    description: Event history
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/EventUniqueEdit"
                "401":
                    $ref: "#/components/responses/401"
        put:
            summary: Update an existing event.
            description: |
                All of the attributes must be present even if they haven't been modified, otherwise the request will fail or the attributes will take their default values, which is likely not what you want.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "log" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/EventID"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EventNew"
            responses:
                "201":
                    description: Event updated successfully.
                "401":
                    $ref: "#/components/responses/401"
        patch:
            summary: Patch an event.
            description: |
                Unlike the `PUT` verb, a `PATCH` does not require all attributes to be provided, but only those that have actually been modified, plus `id`.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "log" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/EventID"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/EventNew"
            responses:
                "201":
                    description: Event updated successfully.
                "401":
                    $ref: "#/components/responses/401"
        delete:
            summary: Delete an event.
            description: |
                Does not actually delete the event but marks it as no longer valid in the database.

                There is no explicit mechanism to *undelete* an event, but its history can be retrieved via the relevant endpoint and the the last (or any other) instance `PUT` back in, which will cause the event to be undeleted while leaving a record of its previous deletion.

                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "log" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/EventID"
            responses:
                "204":
                    description: The event no longer exists.
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/changes/{since}:
        get:
            summary: Get event change history since epoch.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "log" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/Since"
                - $ref: "#/components/parameters/Unique"
            responses:
                "200":
                    description: List of project event changes. If `unique` is given, only the latest version of each event will be returned, otherwise the entire modification history is given, potentially including the same event `id` multiple times.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/EventChanges"

                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/label:
        get:
            summary: Get project labels.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "project" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: List of project label definitions
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Label"
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/qc/results:
        get:
            summary: Get QC results.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "200":
                    description: Project QC results.
                    content:
                        application/json:
                            schema:
                                type: object
                                description: |
                                    The returned object is a tree structure of QC tests and their results.
                "401":
                    $ref: "#/components/responses/401"
        delete:
            summary: Delete all QC results.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthUser: []
                - BearerAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "204":
                    description: |
                        All QC results for the project have been deleted.
                        Note that unless the project has been archived, the QCs will be regenerated in the next run of the deferred tasks process.
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/qc/results/accept:
        post:
            summary: Accept shotpoint QC results.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthUser: []
                - BearerAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: integer
                                description: Event ID of the QC result to mark as accepted.
            responses:
                "204":
                    description: |
                        The QC events referenced in the request body have been marked as accepted. These events will not be exported to Seis+JSON files or derived human-readable reports.
                "401":
                    $ref: "#/components/responses/401"

    /project/{project}/qc/results/unaccept:
        post:
            summary: Unaccept shotpoint QC results.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthUser: []
                - BearerAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
            responses:
                "204":
                    description: |
                        The QC events referenced in the request body are no longer marked as accepted.
                "401":
                    $ref: "#/components/responses/401"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: integer
                                description: Event ID of the QC result to no longer mark accepted.


    /project/{project}/qc/results/sequence/{sequence}:
        get:
            summary: Get sequence QC results.
            description: |
                **Security:** The user must have `read` access to at least one of the organisations that the project gives `read` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/SequenceNumber"
            responses:
                "200":
                    description: Sequence QC results.
                    content:
                        application/json:
                            schema:
                                type: object
                                description: |
                                    The returned object is a tree structure of QC tests and their results for a specific sequence
                "401":
                    $ref: "#/components/responses/401"
        delete:
            summary: Delete sequence QC results.
            description: |
                **Security:** The user must have `write` access to at least one of the organisations that the project gives `write` access to.
            tags: [ "qc" ]
            security:
                - BearerAuthUser: []
                - BearerAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
                - $ref: "#/components/parameters/SequenceNumber"
            responses:
                "204":
                    description: |
                        All QC results for the sequence have been deleted.
                        Note that unless the project has been archived, the QCs will be regenerated in the next run of the deferred tasks process.
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/configuration/{path}:
        get:
            summary: Get project configuration data.
            tags: [ "project" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                -
                    description: Path to configuration object. Nested objects are denoted by `/`.
                    name: path
                    in: path
                    schema:
                        type: string
                    example: /online/line/pattern
            responses:
                "200":
                    description: Parameter value
                    content:
                        application/json:
                            schema:
                                anyOf:
                                    -   type: object
                                    -   type: array
                                    -   type: string
                                    -   type: number
                                    -   type: boolean
                            example:
                                {
                                "flags": "i",
                                "regex": "^.*(10|20)([0-9]{4})([0-9])([0-9]{3})S00000$",
                                "captures": [
                                    "direction",
                                    "line",
                                    "attempt",
                                    "sequence"
                                ]
                                }
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    description: The requested parameter does not exist. Note that the HTTP return code allows us to differentiate between a non-existent parameter and one which is `null` or `undefined`.



    /project/{project}/info/{path}:
        get:
            summary: Get project information data.
            description: Each project has a key/value store where arbitrary information can be stored. The keys are simple strings and the values are JSON objects. This endpoint allows access to this information; either the full object can be returned or a subset of it, by setting the `{path}` accordingly.
            tags: [ "project" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                -
                    description: Item key, optionally followed by an object path, all `/` separated.
                    name: path
                    in: path
                    schema:
                        type: string
                    required: true
                    example: /qc
            responses:
                "200":
                    description: Parameter value, if found. Note that unlike the project configuration endpoint, a non-existent key or non-existent object path still results in a valid response, albeit with an empty body. Clients should be prepared for this.
                    content:
                        application/json:
                            schema:
                                anyOf:
                                    -   type: object
                                    -   type: array
                                    -   type: string
                                    -   type: number
                                    -   type: boolean
                "401":
                    $ref: "#/components/responses/401"


    /project/{project}/meta/{type}/{kind}/{path}:
        get:
            summary: Get metadata
            description: |
                Retrieve metadata from project elements. The valid `{type}` and `{kind}` combinations are as follows:

                Type/Kind   | `preplot` | `raw` | `final`
                ------------|-----------|-------|---------
                `sequences` | ✘         | ✔     | ✔
                `points`    | ✘         | ✔     | ✔
                `lines`     | ✔         | ✘     | ✘

            tags: [ "project", "metadata" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/Project"
                -
                    description: Element type.
                    name: type
                    in: path
                    required: true
                    schema:
                        type: string
                        enum:
                            - sequences
                            - points
                            - lines
                -
                    description: Element kind.
                    name: kind
                    in: path
                    required: true
                    schema:
                        type: string
                        enum:
                            - raw
                            - final
                            - preplot
                -
                    description: Object path.
                    name: path
                    in: path
                    schema:
                        type: string
            responses:
                "200":
                    description: Metadata
                    content:
                        application/json:
                            schema:
                                anyOf:
                                    -   type: object
                                    -   type: array
                                    -   type: string
                                    -   type: number
                                    -   type: boolean
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    description: The requested data does not exist. Note that the HTTP return code allows us to differentiate between a non-existent item and one which is `null` or `undefined`.


    /project/{project}/meta:
        put:
            summary: Update metadata.
            tags: [ "project", "metadata" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/Project"
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                type:
                                    type: string
                                    enum:
                                        - raw
                                        - final
                                        - preplot
                                    default: raw
                                sequence:
                                    type: integer
                                    description: "If `point` is not present or `null`: sequence to be updated; else, the `sequence` / `point` pair is used to select the point the metadata of which is to be updated."
                                line:
                                    type: integer
                                    description: Always used along with `point` to update a specific preplot point. If both `sequence` and `line` are present, `sequence` takes precedence. If `line` is present, the `type` parameter is ignored.
                                point:
                                    type: integer
                                    description: Used together with `sequence` or `line` to update a raw or final shot, or a preplot point, respectively.
                                path:
                                    type: string
                                    description: A `/` separated path into the metadata object to update only a specific attribute while keeping the rest of the metadata intact. If not present, the entire metadata object will be overwritten.
                                value:
                                    type: object
                                    description: The value to be assigned to the metadata attribute (if `path` is present) or to the metadata object itself. It can be any JSON primitive.
            responses:
                "201":
                    description: Metadata updated successfully.
                "401":
                    $ref: "#/components/responses/401"

    /files/{path}:
        get:
            summary: Download files or list directories
            description: |
                * If `{path}` refers to a file, this endpoint will return the file contents with a [`200`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) response code.
                * If `{path}` refers to a directory, this endpoint will return a listing of the directory's immediate children
                with a [`203`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/203) response code, to differentiate this case from the case where an actual JSON file is being downloaded.
                * If `{path}` does not exist or is not accessible, this endpoint responds with a [`404`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404).

                For file downloads, the server will try to guess the correct MIME type and will set [`Content-Type`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) accordingly,
                defaulting to `application/octet-stream` if a more precise type cannot be determined. Pay attention to the [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) header, if present, as responses *may* be compressed, in the presence of a suitable [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) header in the request.
            tags: [ "files" ]
            security:
                - BearerAuthUser: []
                - CookieAuthUser: []
            parameters:
                - $ref: "#/components/parameters/FilePath"
            responses:
                "200":
                    description: File contents.
                    content:
                        "*/*":
                            schema:
                                type: string
                                format: binary
                "203":
                    description: Directory listing.
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    type: object
                                    properties:
                                        path:
                                            type: string
                                            description: Full path on the server.
                                        basename:
                                            type: string
                                            description: File name, including any extension, or directory name.
                                        "Content-Type":
                                            type: string
                                            description: MIME type, defaulting to `application/octet-stream` if a more precise type cannot be determined and the entry refers to a regular file (symbolic links are always resolved), or `inode/directory` if the entry is a directory.
                                        size:
                                            type: integer
                                            description: |
                                                The size of the file in bytes.

                                                If the underlying file system does not support getting the size of the file, this will be 0.
                                        atime:
                                            type: number
                                            description: The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch.
                                        mtime:
                                            type: number
                                            description: The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch.
                                        ctime:
                                            type: number
                                            description:  The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch.
                                        birthtime:
                                            type: number
                                            description: The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch.
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    $ref: "#/components/responses/404"


    /navdata:
        get:
            summary: Get navigation data.
            tags: [ "navdata" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/QueryLimit"
                - $ref: "#/components/parameters/QueryOffset"
                -
                    description: |
                        Select only the values matching this query.

                        Recognised parameters are:

                        * `tstamp`, `tolerance`: temporal restriction to *tstamp ±tolerance*.
                        * `pos`, `radius`: geographic restriction to data within *radius* metres of *pos*.

                        Units and formats:

                        * `tstamp`: An ISO-8601 timestamp.
                        * `tolerance`: A value in milliseconds.
                        * `pos`: Given as longitude, latitude (λ,φ)
                        * `radius`: A value in metres.

                        Default values:

                        * `tolerance`: 1000 ms
                        * `radius`: 1 m
                    name: q
                    in: query
                    schema:
                        type: string
                    example: "tstamp:2021-10-08T10:37:57Z;tolerance:5000;pos:2.479345,59.182838;radius:115"
                -
                    # FIXME Replace this parameter with $ref: "#/components/parameters/QueryProject"
                    description: Subset of attributes to be returned
                    name: fields
                    in: query
                    schema:
                        type: string
                        pattern: "(([^\\s,;:]+)(\\s*[,;\\s]\\s*)?)+"

            responses:
                "200":
                    description: List of navigation data items
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/NavData"
                "401":
                    $ref: "#/components/responses/401"


    /navdata/gis/point:
        get:
            summary: Get navigation data as GeoJSON point features
            tags: [ "navdata" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                - $ref: "#/components/parameters/QueryLimit"
                - $ref: "#/components/parameters/QueryOffset"
            responses:
                "200":
                    description: List of GeoJSON point features
                    content:
                        application/geo+json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/GeoJSONFeature"
                "401":
                    $ref: "#/components/responses/401"


    /navdata/gis/line:
        get:
            summary: Get navigation data as GeoJSON line features
            tags: [ "navdata" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                -
                    description: Maximum number of line vertices
                    name: limit
                    in: query
                    schema:
                        type: integer
                        minimum: 2
                -   $ref: "#/components/parameters/QueryOffset"
            responses:
                "200":
                    description: GeoJSON line feature
                    content:
                        application/geo+json:
                            schema:
                                $ref: "#/components/schemas/GeoJSONFeature"
                "401":
                    $ref: "#/components/responses/401"


    /queue/outgoing/asaqc:
        get:
            summary: Get list of queued items.
            tags: [ "asaqc" ]
            security:
                - BearerAuthGuest: []
                - CookieAuthGuest: []
            parameters:
                -
                    name: status
                    in: query
                    schema:
                        type: string
                        enum: [ "queued", "cancelled", "failed", "sent" ]
                    description: Return only items with matching status. If unspecified, items will not be filtered by status.
                -
                    name: order
                    in: query
                    schema:
                        type: string
                        enum:
                            - created_on
                            - updated_on
                            - not_before
                            - item_id
                            - status
                            - parent_id
                            - project
                            - sequence
                        default: updated_on
                        description: Order the returned items by the specified property.
                -
                    name: dir
                    in: query
                    schema:
                        type: string
                        enum: [ '-', '+' ]
                        default: '-'
                    description: |
                        Specify whether to order items in ascending or descending order.

                        * `-` indicates descending order.
                        * `+` indicates ascending order (in fact, *anything at all* other than `-` means ascending order).
                -
                    name: limit
                    in: query
                    schema:
                        type: integer
                        minimum: 1
                        maximum: 1000
                    description: Maximum number of items to retrieve.
                - $ref: "#/components/parameters/QueryOffset"
            responses:
                "200":
                    description: List of queue items
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/QueueItem"
                            example:
                                [
                                    {
                                        "item_id": 167,
                                        "status": "sent",
                                        "payload": {
                                            "project": "eq21203",
                                            "sequence": 176
                                        },
                                        "results": [
                                            {
                                                "digest": {
                                                    "sha256": {
                                                        "hex": "b67e3a925e0b0845a6e6cfd386acb7841a781b19b994295e251caa635b7c0753"
                                                    }
                                                },
                                                "response": {
                                                    "id": "118d5a69-a235-4306-887c-90a5fd178e79",
                                                    "fileName": "2053721176S00000-NavLog-1.json"
                                                }
                                            },
                                            {
                                                "digest": {
                                                    "sha256": {
                                                        "hex": "9ea30986db8d44400a3352767a8d4cf794ee68b96c793e0e12fba82363d2f5b1"
                                                    }
                                                },
                                                "response": {
                                                    "id": "300d291b-7355-44eb-a15a-5ba5637dac65",
                                                    "fileName": "2053721176S00000-NavLog-1.pdf"
                                                }
                                            }
                                        ],
                                        "created_on": "2021-10-03T18:32:25.480Z",
                                        "updated_on": "2021-10-03T18:35:10.632Z",
                                        "not_before": "1970-01-01T00:00:00.000Z",
                                        "parent_id": 166
                                    },
                                    {
                                        "item_id": 166,
                                        "status": "failed",
                                        "payload": {
                                            "project": "eq21203",
                                            "sequence": 176
                                        },
                                        "results": [
                                            {
                                                "digest": {
                                                    "sha256": {
                                                        "hex": "2fbacfc0414a51d07629c35efa7d29c5012461d16ddcccb89804d1522c10b553"
                                                    }
                                                },
                                                "response": {
                                                    "error": {}
                                                }
                                            },
                                            {
                                                "digest": {
                                                    "sha256": {
                                                        "hex": "4910443e3be2c34990783bb7968746f62dd4ae1fea1c5499ce81f5ba2f262e68"
                                                    }
                                                },
                                                "response": {
                                                    "error": {
                                                        "code": "ECONNREFUSED",
                                                        "type": "system",
                                                        "errno": "ECONNREFUSED",
                                                        "message": "request to https://localhost:3077/vt/v1/api/upload-file-encoded failed, reason: connect ECONNREFUSED 127.0.0.1:3077"
                                                    }
                                                }
                                            }
                                        ],
                                        "created_on": "2021-10-03T18:32:05.585Z",
                                        "updated_on": "2021-10-03T18:32:25.392Z",
                                        "not_before": "1970-01-01T00:00:00.000Z",
                                        "parent_id": null
                                    }
                                ]

                "401":
                    $ref: "#/components/responses/401"
        post:
            summary: Add one or more items to the queue.
            tags: [ "asaqc" ]
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                $ref: "#/components/schemas/QueueRequestASAQC"
            responses:
                "202":
                    description: |
                        All items were added to the queue for processing.

                        Note that this response does not imply that items have been sent or will be delivered, or that an entity matching the request even exists. It is merely a promise to attempt a transfer at some later time, if the item exists and the remote server is reachable.
                "400":
                    description: |
                        The request was malformed or had invalid data.

                        If a request consisting of multiple items fails, none of the items get added to the queue.
                "401":
                    $ref: "#/components/responses/401"

    /queue/outgoing/asaqc/{id}:
        delete:
            summary: Cancel a queued transfer.
            description: Use this request to cancel a queued transfer before it is sent. This endpoint does not return a body, success or failure is denoted by the HTTP response status code.
            tags: [ "asaqc" ]
            parameters:
                -
                    name: id
                    in: path
                    schema:
                        type: integer
                    description: The ID of a queued request.
            responses:
                "204":
                    description: |
                        Request successfully cancelled. No data has been sent or will be sent.

                        * If the referenced request had status `queued`, its status was changed to `cancelled`.
                        * If the referenced request had status `failed` and there existed one or more requests with status `queued` and `parent_id` equal to this request's ID, their status was changed to `cancelled`.
                "401":
                    $ref: "#/components/responses/401"
                "404":
                    description: The request does not exist or it has already been fulfilled and cannot therefore be cancelled.


    /version:
        get:
            summary: Get version information
            tags: [ "misc" ]
            security: null
            responses:
                "200":
                    description: Version data
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/SoftwareVersion"


    /diagnostics:
        get:
            summary: Get server diagnostics
            description: This endpoint returns server information useful for diagnostics and monitoring.
            tags: [ "misc" ]
            security: null
            responses:
                "200":
                    description: Diagnostics data
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/ServerDiagnostics"


    /user:
        get:
            summary: Get list of users
            description: |
                Returns a list of users belonging to the organisation(s) that the requesting
                user has `write` or `edit` access to.
            tags: [ "users" ]
            security:
                - BearerAuthAdmin: []
                - CookieAuthAdmin: []
            responses:
                "200":
                    description: |
                        List of users

                        * If the requesting user has only `write` access to the organisation, a limited subset of details (`SimpleUser`) will be returned
                        * If the requesting user has `edit` access, a full `User` entity will be returned
                        * For a requesting user that belongs to multiple organisations with different access levels, a mix of `SimpleUser` and `User` entities may be returned.

                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    anyOf:
                                        - $ref: "#/components/schemas/SimpleUser"
                                        - $ref: "#/components/schemas/User"

        post:
            summary: Create a user
            description: |
                Via this endpoint, an existing user can create new users on organisations for which he has `edit` access.
            tags: [ "users" ]
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/User"
            responses:
                "200":
                    description: |
                        New user details

                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/User"


    /user/{id}:

        get:
            summary: Get user details
            tags: [ "users" ]
            responses:
                "200":
                    description: |
                        User details

                        * If the requesting user has only `write` access to the organisation(s) of the requested user, a limited subset of details (`SimpleUser`) will be returned
                        * If the requesting user has `edit` access to any of the organisations of the requested user, a full `User` entity will be returned
                        * If the requesting and the requested users are the same, a full `User` entity will be returned (this reveals the login method used)

                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/SimpleUser"
                                    - $ref: "#/components/schemas/User"

        put:
            summary: Edit a user
            description: |
                A user can be edited either by himself (`NamedUser` only) or by someone with `edit`
                access to at least one of the user's organisations.

                In the case of a `NamedUser` self edit, only certain properties may be modified.
            tags: [ "users" ]
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            oneOf:
                                -
                                    $ref: "#/components/schemas/User"
                                -
                                    $ref: "#/components/schemas/NamedUserSelfEditable"
            responses:
                "200":
                    description: |
                        New user details

                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/User"

        delete:
            summary: Delete a user
            description: |
                **Deleting a user is an irreversible action. Use with care!**
            tags: [ "users" ]
            responses:
                "204":
                    description: |
                        The user has been deleted
                "404":
                    description: |
                        The target user does not exist or the requesting user does not
                        have sufficient rights over it

    /user/validate/{validation_id}:
        get:
            summary: Request user validation
            tags: [ "users" ]
            responses:
                "200":
                    description: |
                        When a user identified by a user name and password is created and an email address is provided, the new user receives an email with a link to this endpoint. In this endpoint, the user will acknowledge that he wants to proceed with registration and enter a password.

                        This endpoint is also used when the email address of an existing user is changed, to validate the new address. In this case, no password prompt is issued.

                        Finally, this endpoint can be used in case the user forgets his password, to enter a new one.
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/UserValidationRequest"

        post:
            summary: Confirm user validation request
            tags: [ "users" ]
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/UserValidationResponse"
            responses:
                "204":
                    summary: Validation successful
                    description: |
                        The server has accepted and processed the validation response.
                "404":
                    summary: Not found
                    description: |
                        No validation request exists with this `id`. It may have never existed or it may have already expired.




    /login:
        post:
            summary: Request a user token.
            description: Users are identified by a username and a password. Usernames do not need to be unique, meaning that the same username can have different passwords and each user/password combination can have its own role. For instance, a user could have one password for everyday use and another to log in as administrator.
            tags: [ "login" ]
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                user:
                                    type: string
                                    description: User name to log in as
                                password:
                                    type: string
                                    description: Password corresponding to given user and requested role
            responses:
                "204":
                    description: Login successful. The token is returned in a `Set-Cookie` header.
                "401":
                    $ref: "#/components/responses/401"


    /logout:
        get:
            summary: Log out (GET alternative).
            description: |
                Visiting this endpoint will cause the authorisation cookie `JWT` to be overwritten with an expired cookie, hopefully causing user agents to forget the previous token.

                Note that this does not necessarily mean that the user *will* be logged out. The only way to truly log out, other than removing the user from the system, is for the client to forget its token or let it expire.

                Note that the user may be logged back in automatically on the next API request if they are connecting from an authorised network or host.

            tags: [ "login" ]
        post:
            summary: Log out (POST alternative).
            description: Same as its `GET` counterpart. It does not require a body and if one is sent it will be ignored.
            tags: [ "login" ]
