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:
* `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.
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.
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.
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.
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.
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.
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`**.
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."
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.
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.
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`
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).
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.
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).
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.
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.
- 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.
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.
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.
*Onlyshown 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.
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",
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
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.)
- 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
# 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
400error.
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:
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
*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.
"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.
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:|
**Deletinga 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.
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.
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.
