API reference

IMPORTANT: STILL UNDER CONSTRUCTION! The endpoints, columns, fields and related models are auto-generated from the code, so these should be correct and up to date! Any questions, please contact Ariell at Greybits.

Contents

API Authentication

API can be tested using a logged in browser session. To authenticate external services/scripts, you will need to activate the API_TOKEN for your account and set it in the HTTP header for requests made to the API:
  • X-auth-token="YOUR-API-TOKEN"
where YOUR-API-TOKEN is the value of your API TOKEN. You are not logged in. You need to log in to view/manage your API TOKEN.

Resource collections & API endpoints

ENDPOINTS
METHODENDPOINT
POST

/api/annotation

Create new annotation object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Enforce implied permissions from parent annotation_set (post_auth_preprocessor)

GET

/api/annotation

Get list of annotation objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, created_at, updated_at, annotation_set_id, data, label, label.id, label.name, label.uuid, label.parent_id, label.label_scheme_id, point, point.media_id, point.x, point.y, point.t, point.data, point.annotation_set_id, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, observation_count, object_id (see below for more details)

Preprocessors:

  • Filter results based on permissions from parent annotation_set (get_many_auth_preprocessor)

GET

/api/annotation/<id>

Get single annotation object with pk field matching param id

Included fields:
id, created_at, updated_at, annotation_set_id, data, label, label.id, label.name, label.uuid, label.parent_id, label.label_scheme_id, point, point.media_id, point.x, point.y, point.t, point.data, point.annotation_set_id, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, observation_count, object_id (see below for more details)

Preprocessors:

  • Enforce implied permissions from parent annotation_set (get_single_auth_preprocessor)

DELETE

/api/annotation/<id>

Delete single annotation object with pk field matching param id

Preprocessors:

  • Enforce implied permissions from parent annotation_set (delete_auth_preprocessor)

PATCH

/api/annotation

Batch update annotation objects. Set q in querystring to filter selected annotations as per Making API search queries. Returned results are pre-filtered for only the annotations that come from annotation_sets where current_user_can_edit is set to true. As a safety measure, there is a limit of 200 annotations that can be updated in a single request.

CAUTION: this endpoint can batch update many annotations in a single request! If used incorrectly, you can loose your annotations and any annotations that have been shared with you for which you have been granted edit access. Please use with caution. TIP: Test your search query (q) on a GET request first to see what is returned before updating.

PATCH request data must be JSON with the following fields:

{ "label_id": ..., "tags": [...], "comment": "..." }
Where label_id is the id of the label object that you would like to assign to the list of matched annotations. Setting label_id to false will reset the label and any assigned tags. tags is a list of tag.id's and comment is a string that can be assigned to each annotation.

# Example: batch change ALL annotations matching filter. Set label_id=7326 ("Ecklonia radiata") for all annotations in an annotation_set annotation_set_id=2171 annotated by user user_id=1 with a label matching label_id=7331 ("Sargasm spp")

# PATCH: (TIP first run as GET request to check filter before PATCHING) /api/annotation?q={"filters": [{"name": "annotation_set_id", "op": "eq", "val": 2171}, {"name": "label_id", "op": "eq", "val": 7331}, {"name": "user_id", "op": "eq", "val": 1}]}

# JSON PATCH DATA: { "label_id": 7326 }

PATCH

/api/annotation/<int:id>

None

DELETE

/api/annotation/<int:annotation_id>/tag/<int:tag_id>

None

PATCH

/api/annotation/<int:id>/link/<int:link_id>

Updates parent_id of annotation to group observations of the same object. If link_id points to a child annotation, the observation will be linked to its parent. An observation group is used to link observations of the same object that has been annotated multiple times.

DELETE

/api/annotation/<int:id>/link

Unlink this annotation from the observation group. If it is a group parent, the first child will be set as the new parent. An observation group is used to link observations of the same object that has been annotated multiple times.

PATCH

/api/annotation/<int:id>/link

Set this annotation as the parent of the observation group. An observation group is used to link observations of the same object that has been annotated multiple times.

GET

/api/annotation/tally/<group_by>

Get a tally of annotations grouped by different properties. group_by can be one of [month, user, platform, campaign, deployment, label, affiliation^, usergroup^]. Set q in querystring to filter selected annotations as per Making API search queries. Note, the same query in q can be applied to all group_by types to filter the list of annotations that are included in the tally. Results are also paginated with a default of 500 and a maximum on 5000 returned per page. This can be controlled by setting the results_per_page parameter in the query string. Returned results are pre-filtered to return only the annotations that have been labeled (label_id != null). Also accepts a query string parameter template which formats the data using a predefined template. Some example templates include: data.html which returns an HTML table, json.html which returns HTML-formatted JSON, data.csv which returns a CSV file for download. If left blank, raw JSON will be returned.

^ NOTE: the counts in the affiliation and usergroup tally should be interpreted with care. If someone belongs to more than one group, then their annotations will contribute to both so they may be double counted. The corollary of that is if someone has not linked themselves to an affiliation or group, then their annotations will not be counted in the tally.

# Example: tally of annotations for top 500 most commonly used labels returned as an HTML table
/api/annotation/tally/label?template=data.html&results_per_page=500

# Example: tally of annotations for the top 1000 users returned as a CSV file /api/annotation/tally/user?&results_per_page=1000&template=data.csv

# Example: tally of annotations for the top 20 affiliations returned as an HTML table /api/annotation/tally/affiliation?&results_per_page=20&template=data.html

# Example: tally of annotations by the top 200 usergroups returned as an HTML table /api/annotation/tally/usergroup?&template=data.html&results_per_page=200

# Example: tally of annotations by month between 2020-01-01 and 2021-01-01 returned as an HTML table /api/annotation/tally/month?q={"filters": [{"name":"updated_at","op":"gt","val":"2020-01-01"}, {"name":"updated_at","op":"lt","val":"2021-01-01"}] }&template=data.html

# Example: tally of annotations by platform returned as raw JSON /api/annotation/tally/platform

# Example: tally of annotations by campaign returned as a HTML-formatted JSON /api/annotation/tally/campaign?&template=json.html

# Example: tally of annotations for top 2000 deployments returned as an HTML table /api/annotation/tally/deployment?&template=data.html&results_per_page=2000

# Example: tally annotations by deployment filtered by annotation_set.usergroup with ID=63 returned as an HTML table /api/annotation/tally/deployment?&results_per_page=2000&template=data.html&q={"filters": [{"name":"annotation_set","op":"has","val": {"name":"usergroups","op":"any","val": {"name":"id","op":"eq","val":63}}}]}

# Example: tally of annotations for the top 20 users for platform(s) containing "IMOS" in their name that were labeled during the year 2020. Return the result as an HTML table using the template "data.html", GET: /api/annotation/tally/user?q={"filters": [{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"deployment","op":"has","val": {"name":"platform","op":"has","val": {"name":"name","op":"ilike","val":"%IMOS%"}}}}}, {"name":"created_at","op":"gt","val":"2020-01-01"}, {"name":"created_at","op":"lt","val":"2021-01-01"}] }&results_per_page=20&template=data.html

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
label_id Integer() None True None - label.id Foreign key id for related label (or class label)
created_at DateTime() function True None - - Creation time (UTC)
updated_at TIMESTAMP() function True None - - Updated time (UTC)
user_id Integer() None False None - users.id Foriegn key id for owner user object
point_id Integer() None False None - point.id Foriegn key id for point object
annotation_set_id Integer() None False None - annotation_set.id Foriegn key id for annotation_set object
comment Text() None True None - - User comment
parent_id Integer() None True None - annotation.id id of parent annotation for group of linked observations
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE Related label object
user users MANYTOONE Related owner user object
point point MANYTOONE Related point object
annotation_set annotation_set MANYTOONE Related annotation_set object
parent annotation MANYTOONE Parent annotation in a linked set of observations
children annotation ONETOMANY Collection of linked child observations
annotation_tags annotation_tags ONETOMANY Collection of annotation_tags associations
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
tags tag annotation_tags Proxy attribute that presents the linked tag objects from the annotation_tags collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property - BOOLEAN, whether or not this annotation has a linked parent annotation (queryable)
timestamp property - The in-situ timestamp for when the annotated object was captured/sampled in the media frame. Returns media.timestamp_start + point.t if point.t is set, otherwise it just returns media.timestamp_start
data property - JSON data containing optional properties for this resource
timestamp_proximity method ts Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
distance method lat, lon FLOAT, distance (in meters) of closest linked pose relative to lat and lon (which are both in decimal degrees)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
color method Implied color code for this annotation based on label assignment
current_user_can_edit method BOOLEAN, whether or not the current user has edit rights for this annotation as implied by the permissions of the parent annotation_set
observation_count method INT, denoting the number of linked observations of this object
pose method Properties for related pose item excluding posedata fields
pose_data method Properties for related pose item including any linked posedata fields
suggested_tags method List of suggested tag implied from label definition
tag_names method None
object_id property ID of observation group. Returns None if annotation is not linked to other observations.
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_set

Create new annotation_set object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/annotation_set/<id>

Update single annotation_set object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (patch_auth_preprocessor)

GET

/api/annotation_set

Get list of annotation_set objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, parent_id, description, user, user.id, user.username, user.first_name, user.last_name, created_at, children, media_collection, media_collection.id, media_collection.name, label_scheme, label_scheme.id, label_scheme.name, annotation_count, data, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_exemplar, annotation_count, usergroup_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)

GET

/api/annotation_set/<id>

Get single annotation_set object with pk field matching param id

Included fields:
id, name, parent_id, description, user, user.id, user.username, user.first_name, user.last_name, created_at, children, media_collection, media_collection.id, media_collection.name, label_scheme, label_scheme.id, label_scheme.name, annotation_count, data, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_exemplar, annotation_count, usergroup_count, media_count, point_count, unannotated_point_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. (get_single_auth_preprocessor)

DELETE

/api/annotation_set/<id>

Delete single annotation_set object with pk field matching param id

Preprocessors:

  • None (delete_auth_preprocessor)

POST

/api/annotation_set/<int:instance_id>/group/<int:group_id>

Add object with id instance_id to group with id group_id

DELETE

/api/annotation_set/<int:instance_id>/group/<int:group_id>

Remove resource with id instance_id from group with id group_id

GET

/api/annotation_set/<int:id>/export

Export annotations collection from annotation_set matching id. Search queries are executed on the annotation model.

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed columns include: id, label.id, label.name, label.lineage_names, comment, tag_names, label.uuid, updated_at, user.username, point.id, point.x, point.y, point.t, point.data, point.media.id, point.media.key, point.media.path_best, point.media.timestamp_start, point.media.path_best_thm, point.pose.timestamp, point.pose.lat, point.pose.lon, point.pose.alt, point.pose.dep, point.pose.data, point.pose.id, point.media.deployment.key, point.media.deployment.campaign.key, point.media.deployment.id, point.media.deployment.campaign.id, object_id

See annotation model columns, relations and attributes for more information on each of the included fields.

# Example1: get all columns as a downloaded CSV file, only point annotations - filter out whole frame labels
/api/annotation_set/2194/export?template=dataframe.csv&f={"operations":[{"module":"pandas", "method":"json_normalize"}]}&q={"filters":[{"name":"point", "op":"has", "val":{"name":"has_xy", "op":"eq","val":true}}]}

# Example2: aggregate label counts per frame (percent cover, no point information) as a downloaded csv /api/annotation_set/2171/export?template=dataframe.csv&include_columns=["label.name", "label.lineage_names", "point.media.key", "point.pose.timestamp", "point.pose.lat", "point.pose.lon", "point.pose.alt", "point.pose.dep"]&f={"operations":[{"module":"pandas", "method":"json_normalize"},{"method":"fillna", "kwargs":{"value":"-"}},{"module":"pandas", "method":"count_unstack", "kwargs":{"columns":["label.id", "label.uuid", "label.name", "label.lineage_names", "comment", "tag_names"]}}]}

# Example3: show selected columns as an HTML table in the browser, filter out unlabeled annotations /api/annotation_set/2171/export?template=dataframe.html&disposition=inline&include_columns=["label.name","label.lineage_names", "updated_at", "point.x", "point.y", "point.media.key", "point.pose.timestamp", "point.pose.lat", "point.pose.lon", "point.pose.alt", "point.pose.dep", "point.media.deployment.key", "point.media.deployment.campaign.key"]&f={"operations":[{"module":"pandas", "method":"json_normalize"}]}&q={"filters":[{"name":"label_id", "op":"is_not_null"}]}

# Example4: show HTML table in browser with tally of label counts (can be refreshed for readable live summary) /api/annotation_set/2171/export?template=dataframe.html&disposition=inline&include_columns=["label.uuid","label.name","label.lineage_names","label.id"]&f={"operations":[{"module":"pandas","method":"json_normalize"},{"module":"pandas","method":"groupby_count"}]}&q={"filters":[{"name":"label_id","op":"is_not_null"}]}

NB: the UI contains an "ADVANCED" option which can help build more complex export queries.

GET

/api/annotation_set/<int:id>/media

None

GET

/api/annotation_set/<int:id>/annotations

Returns list of annotation objects contained in the annotation_set with an ID matching id. The results can be filtered and searched. See Making API search queries for instructions on making search queries. In addition it accepts include_columns and include_methods query parameters which override returned fields of annotation model.

GET

/api/annotation_set/<int:id>/annotations/<group_by>

Returns lists of the labels used in the annotation_set with an ID matching id. The group_by parameter must one of [label_updated, label_frequency, deployment] which returns the most recently used labels, counts by label (most frequently used) or counts by deployment, respectively. The number of results and page can be controlled with the results_per_page and page query parameters, respectively.

POST

/api/annotation_set/<int:annotation_set_id>/media/<int:media_id>

Add the media object with the ID media_id to the media_collection of the annotation_set matching annotation_set_id

DELETE

/api/annotation_set/<int:annotation_set_id>/media/<int:media_id>

Remove the media object with the ID media_id from the media_collection of the annotation_set matching annotation_set_id

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
name String(length=80) None False None - - None
description Text() None True None - - None
media_collection_id Integer() None False None - media_collection.id None
label_scheme_id Integer() None False None - label_scheme.id None
user_id Integer() None False None - users.id Foreign key reference for ID of related owner users model
created_at DateTime() function False None - - None
parent_id Integer() None True None - annotation_set.id None
is_exemplar Boolean() False True None - - None
type String(length=80) base True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media_collection media_collection MANYTOONE None
label_scheme label_scheme MANYTOONE None
user users MANYTOONE Related owner users model
parent annotation_set MANYTOONE None
usergroups groups MANYTOMANY List of groups objects that contain this resource
points point ONETOMANY List of point objects
annotations annotation ONETOMANY List of related annotation objects
children annotation_set ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property - BOOLEAN, whether or not this annotation has a linked parent annotation
is_public property - Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property - Whether or not the currently logged in user is the owner of this object
current_user_is_member property - Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property - Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property - Whether or not the current user has permission to view this object
current_user_can_edit property - Whether or not the current logged in user has edit permission (owner or edit_member)
data property - JSON data containing optional properties for this resource
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_count method None
media_count method None
point_count method None
unannotated_point_count method None
usergroup_count method None
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_tags

Create new annotation_tags object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/annotation_tags

Get list of annotation_tags objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/annotation_tags/<annotation_id>

Get single annotation_tags object with pk field matching param annotation_id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/annotation_tags/<annotation_id>

Delete single annotation_tags object with pk field matching param annotation_id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
annotation_id Integer() None False None True annotation.id id of linked annotation
tag_id Integer() None False None True tag.id id of linked tag
assoc_created_at DateTime() function True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
annotation annotation MANYTOONE Linked annotation object
tag tag MANYTOONE Linked tag object
ENDPOINTS
METHODENDPOINT
GET

/api/campaign-deployment/<resource>

:param resource: :return:

Examples:

# search campaign-deployments for "gbr" /api/campaign-deployment/deployment?q={"filters":[{"or":[{"name":"key","op":"ilike","val":"%gbr%"},{"name":"campaign","op":"has","val":{"name":"key","op":"ilike","val":"%gbr%"}}]}]} # match list of deployment keys (campaign-deployment) /api/campaign-deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for deployments /api/campaign-deployment/deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for IDs and not keys /api/campaign-deployment/deployment?q={"filters":[{"name":"id","op":"in","val":[9495,9491]}]}

GET

/api/campaign-deployment

:param resource: :return:

Examples:

# search campaign-deployments for "gbr" /api/campaign-deployment/deployment?q={"filters":[{"or":[{"name":"key","op":"ilike","val":"%gbr%"},{"name":"campaign","op":"has","val":{"name":"key","op":"ilike","val":"%gbr%"}}]}]} # match list of deployment keys (campaign-deployment) /api/campaign-deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for deployments /api/campaign-deployment/deployment?q={"filters":[{"name":"key","op":"in","val":["r20071004_013437_gbr_05_noggin_grids","r20071010_230932_gbr_09_hydrographers_leg"]}]} # as above but for IDs and not keys /api/campaign-deployment/deployment?q={"filters":[{"name":"id","op":"in","val":[9495,9491]}]}

ENDPOINTS
METHODENDPOINT
POST

/api/campaign

Create new campaign object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)

PATCH

/api/campaign/<id>

Update single campaign object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)

GET

/api/campaign

Get list of campaign objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
color, id, key, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/campaign/<id>

Get single campaign object with pk field matching param id

Included fields:
color, id, key, name, user_id, extent, stats, platforms (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/campaign/<id>

Delete single campaign object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/campaign/map

Deployment resource

Minimal Deployment Resource for map data - result is cached for fast loading. Cache is cleared when new deployments are saved.

:param GET: json: q: restless search query. :returns GET: json: a json string containing the structure of stuff

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - None
key String(length=80) None False True - - None
path Text() None True None - - None
color String(length=10) function True False - - None
description Text() None True None - - None
user_id Integer() None False None - users.id None
created_at DateTime() function False None - - None
media_path_pattern Text() None True None - - None
thm_path_pattern Text() None True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
deployments deployment ONETOMANY None
info campaigninfo ONETOMANY None
files campaign_file ONETOMANY None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
deployment_count method None
extent method Compute spatial extent of Campaign :return: list with format [[SW_LAT, SW_LON],[NE_LAT,NE_LON]]
file_count method None
latlon method None
media_count method None
platforms method None
stats method None
timestamp_range method None
ENDPOINTS
METHODENDPOINT
POST

/api/campaign_file

Create new campaign_file object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/campaign_file/<id>

Update single campaign_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/campaign_file

Get list of campaign_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/campaign_file/<id>

Get single campaign_file object with pk field matching param id

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/campaign_file/<id>

Delete single campaign_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/campaign_file/<int:fid>/data

Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form:

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.

POST

/api/campaign_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
last_save JSON() None True None - - Sequence of file operations performed at last save
name Text() None False False - - The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - - The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - - The description of the file (optional)
_rawfiledata LargeBinary() None True None - - The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - - Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
user_id Integer() None False None - users.id None
campaign_id Integer() None False None - campaign.id None
created_at DateTime() function True None - - None
updated_at DateTime() function True None - - Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
campaign campaign MANYTOONE None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property None
ENDPOINTS
METHODENDPOINT
POST

/api/campaigninfo

Create new campaigninfo object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/campaigninfo

Get list of campaigninfo objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, description, created_at, campaign_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/campaigninfo/<id>

Get single campaigninfo object with pk field matching param id

Included fields:
name, description, created_at, campaign_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/campaigninfo/<id>

Delete single campaigninfo object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - None
description Text() None False None - - None
created_at DateTime() function False None - - None
campaign_id Integer() None False None - campaign.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
campaign campaign MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/datasource

Create new datasource object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/datasource/<id>

Update single datasource object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/datasource

Get list of datasource objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, campaign_search, datafile_pattern, datafile_search, deployment_search, media_pattern, mediadir_search, thumb_pattern, thumbdir_search, urlbase_browse, datafile_operations, datasource_type, datasource_type.id, datasource_type.name, platform, platform.id, platform.name, user_id, created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/datasource/<id>

Get single datasource object with pk field matching param id

Included fields:
id, name, campaign_search, datafile_pattern, datafile_search, deployment_search, media_pattern, mediadir_search, thumb_pattern, thumbdir_search, urlbase_browse, datafile_operations, datasource_type, datasource_type.id, datasource_type.name, platform, platform.id, platform.name, user_id, created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/datasource/<id>

Delete single datasource object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False True - - None
campaign_search Text() None True None - - None
datafile_pattern Text() None True None - - None
datafile_search Text() None True None - - None
deployment_search Text() None True None - - None
media_pattern Text() None True None - - None
mediadir_search Text() None True None - - None
thumb_pattern Text() None True None - - None
thumbdir_search Text() None True None - - None
urlbase_browse Text() None True None - - None
datafile_operations JSON() None True None - - None
datasource_type_id Integer() None False None - datasource_type.id None
platform_id Integer() None False None - platform.id None
user_id Integer() None False None - users.id None
created_at DateTime() function False None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
datasource_type datasource_type MANYTOONE None
platform platform MANYTOONE None
user users MANYTOONE None
deployments deployment ONETOMANY None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment

Create new deployment object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/deployment/<id>

Update single deployment object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/deployment

Get list of deployment objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, key, id, created_at, campaign, campaign.id, campaign.name, platform, platform.id, platform.name, is_valid, color (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/deployment/<id>

Get single deployment object with pk field matching param id

Included fields:
name, key, id, created_at, campaign, campaign.id, campaign.name, platform, platform.id, platform.name, is_valid, color, user_id, created_at, description, campaign.key, platform, platform.id, platform.name, platform.key, files, files.id, files.name, files.file_url, latlon, media_count, pose_stats, layers (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/deployment/<id>

Delete single deployment object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/deployment/map

Deployment resource

Minimal Deployment Resource for map data - result is cached for fast loading. Cache is cleared when new deployments are saved.

:param GET: json: q: restless search query. :returns GET: json: a json string containing the structure of stuff

POST

/api/deployment/upload

None

GET

/api/deployment/<int:id>/export

None

GET

/api/deployment/<int:id>/stats

None

GET

/api/deployment/<int:id>/ecoregion

Get ecoregion info from ESRI API Marine Ecoregions Of the World (MEOW) feature layer. Uses latlon of deployment to determine the relevant ecoregion. Accepts querystring parameter: fields which is a comma-separated list of properties to return, which can be a subset of: fields = FID, ECO_CODE, ECOREGION, PROV_CODE, PROVINCE, RLM_CODE, REALM, ALT_CODE, ECO_CODE_X, Lat_Zone, Shape__Area, Shape__Length if not set, it will default to fields=*, which will return all properties.

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - None
key String(length=80) None False None - - None
path Text() None True None - - None
campaign_id Integer() None False None - campaign.id None
user_id Integer() None False None - users.id None
description Text() None True None - - None
created_at DateTime() function False None - - None
platform_id Integer() None False None - platform.id None
datasource_id Integer() None False None - datasource.id None
is_valid Boolean() True True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
campaign campaign MANYTOONE None
user users MANYTOONE None
platform platform MANYTOONE None
datasource datasource MANYTOONE None
media media ONETOMANY None
events deployment_event ONETOMANY None
files deployment_file ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
latlon property - None
timestamp property - None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
color method None
extent method Compute spatial extent of Campaign :return: list with format [[SW_LAT, SW_LON],[NE_LAT,NE_LON]]
layers method None
media_count method None
timestamp_range method None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event

Create new deployment_event object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/deployment_event/<id>

Update single deployment_event object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/deployment_event

Get list of deployment_event objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
media, user_id, description, timestamp, created_at, pose, deployment, deployment.name, deployment.key, deployment.id, deployment.created_at, deployment.campaign_id, deployment_event_type, user, user.username, user.info, user.first_name, user.last_name, user.email, user.id, deployment_event_type_id, media_id, deployment_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/deployment_event/<id>

Get single deployment_event object with pk field matching param id

Included fields:
media, user_id, description, timestamp, created_at, pose, deployment, deployment.name, deployment.key, deployment.id, deployment.created_at, deployment.campaign_id, deployment_event_type, user, user.username, user.info, user.first_name, user.last_name, user.email, user.id, deployment_event_type_id, media_id, deployment_id, id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/deployment_event/<id>

Delete single deployment_event object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
description Text() None False None - - None
user_id Integer() None False None - users.id None
created_at DateTime() function False None - - None
timestamp DateTime() function False None - - None
pose_id Integer() None True None - pose.id None
media_id Integer() None True None - media.id None
deployment_event_type_id Integer() None False None - deployment_event_type.id None
deployment_id Integer() None False None - deployment.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
pose pose MANYTOONE None
media media MANYTOONE None
deployment_event_type deployment_event_type MANYTOONE None
deployment deployment MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event_type

Create new deployment_event_type object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/deployment_event_type/<id>

Update single deployment_event_type object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/deployment_event_type

Get list of deployment_event_type objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
name, id, data (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/deployment_event_type/<id>

Get single deployment_event_type object with pk field matching param id

Included fields:
name, id, data (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/deployment_event_type/<id>

Delete single deployment_event_type object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
name String(length=80) None False True - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
deployment_events deployment_event ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
data property - JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_file

Create new deployment_file object. Expects JSON. Fields shown in MODEL COLUMNS below. Add user_id to post payload if not supplied

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/deployment_file/<id>

Update single deployment_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/deployment_file

Get list of deployment_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/deployment_file/<id>

Get single deployment_file object with pk field matching param id

Included fields:
user_id, description, iscompressed, campaign_id, file_url, id, name, last_save (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/deployment_file/<id>

Delete single deployment_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/deployment_file/<int:fid>/data

Deployment file resource. Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form:

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.

Example1: convert CSV file into serialized, nested JSON expected for media resource and batch save rows to the related deployment.media collection for this model

/api/deployment_file/2/data?save={"collection": "deployment.media"}&f={"operations": [{"module": "pandas", "method": "read_csv", "kwargs": {"parse_dates": ["time"], "skiprows": 2, "usecols": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]}}, {"method": "rename", "kwargs": {"columns": {"image_filename": "key", "longitude": "pose.lon", "latitude": "pose.lat", "depth_sensor": "pose.data.dep", "altitude_sensor": "pose.alt", "depth": "pose.dep", "sea_water_temperature": "pose.data.temp", "sea_water_salinity": "pose.data.salinity", "chlorophyll_concentration_in_sea_water": "pose.data.chlorophyll", "backscattering_ratio": "pose.data.backscater", "colored_dissolved_organic_matter": "pose.data.colored_dissolved_organic_matter", "time": "timestamp_start", "cluster_tag": "pose.data.cluster_tag"}}}, {"method": "to_dict", "kwargs": {"orient": "records"}}, {"module": "data", "method": "unflatten_dicts", "kwargs": {}}]}

Example 2: similar to above, but perform an update rather than an insert. Can optinally create missing. This is slower.

/api/deployment_file/4/data?save={"collection": "deployment.media", "update_existing": true, "match_on": ["key"], "create_missing": true}&f={"operations": [{"module": "pandas", "method": "read_csv", "kwargs": {"parse_dates": ["time"], "skiprows": 2, "usecols": [2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]}}, {"method": "rename", "kwargs": {"columns": {"image_filename": "key", "longitude": "pose.lon", "latitude": "pose.lat", "depth_sensor": "pose.data.dep", "altitude_sensor": "pose.alt", "depth": "pose.dep", "sea_water_temperature": "pose.data.temp", "sea_water_salinity": "pose.data.salinity", "chlorophyll_concentration_in_sea_water": "pose.data.chlorophyll", "backscattering_ratio": "pose.data.backscater", "colored_dissolved_organic_matter": "pose.data.colored_dissolved_organic_matter", "time": "timestamp_start", "cluster_tag": "pose.data.cluster_tag"}}}, {"method": "to_dict", "kwargs": {"orient": "records"}}, {"module": "data", "method": "unflatten_dicts", "kwargs": {}}]}

POST

/api/deployment_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
last_save JSON() None True None - - Sequence of file operations performed at last save
name Text() None False False - - The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - - The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - - The description of the file (optional)
_rawfiledata LargeBinary() None True None - - The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - - Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
user_id Integer() None False None - users.id None
deployment_id Integer() None False None - deployment.id None
created_at DateTime() function False None - - None
updated_at DateTime() function True None - - Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
deployment deployment MANYTOONE None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property None
ENDPOINTS
METHODENDPOINT
GET

/api/group_types

Get list of group_types objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/group_types/<id>

Get single group_types object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=128) None False None - - None
ENDPOINTS
METHODENDPOINT
POST

/api/groups

Create new groups object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Handle group_type_name parameter and secure against membership/dataset tampering (group_data_preprocessor)

Postprocessors:

  • None (post_postprocessor)

PATCH

/api/groups/<id>

Update single groups object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Handle group_type_name parameter and secure against membership/dataset tampering (group_data_preprocessor)
  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/groups

Get list of groups objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, is_public, dua_link, user, user.id, user.first_name, user.last_name, user.username, is_restricted, group_type, groupinfo, created_at, current_user_is_edit_member, current_user_is_member, current_user_is_owner, current_user_can_share_data, current_user_can_add_member, current_user_has_agreed, current_user_is_pending_approval, requires_agreement, requires_approval, member_count, pending_member_count (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/groups/<id>

Get single groups object with pk field matching param id

Included fields:
id, name, is_public, dua_link, user, user.id, user.first_name, user.last_name, user.username, is_restricted, group_type, groupinfo, created_at, current_user_is_edit_member, current_user_is_member, current_user_is_owner, current_user_can_share_data, current_user_can_add_member, current_user_has_agreed, current_user_is_pending_approval, requires_agreement, requires_approval, member_count, pending_member_count, description, dataset_counts (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/groups/<id>

Delete single groups object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=128) None False None - - Name of Group
is_public Boolean() False True None - - Whether or not contents are publicly viewable
is_restricted Boolean() True True None - - Whether or not members can see other member's datasets
requires_approval Boolean() True True None - - Whether or not custodian approval is required
requires_agreement Boolean() True True None - - Whether or not members need to agree to Data Usage Agreement (DUA)
description Text() None True None - - Extra information about the Group
dua_link Text() None True None - - Data Usage Agreement (DUA) link. Must be an HTTP accessible, embeddable document
user_id Integer() None True None - users.id id of group custodian user
group_type_id Integer() None False None - group_types.id id of related group_type
groupinfo Text() None True None - - Shorter description / tagline of Group
created_at DateTime() function False None - - Datetime of creation
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE Related user for group custodian
group_type group_types MANYTOONE related group_type object
members users MANYTOMANY None
usergroups usergroups ONETOMANY None
shared_label_schemes label_scheme MANYTOMANY None
shared_annotation_sets annotation_set MANYTOMANY None
shared_media_collections media_collection MANYTOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
current_user_is_owner property - :return:
current_user_is_pending_approval property - :return:
current_user_is_member property - :return:
current_user_is_edit_member property - :return:
current_user_can_share_data property - BOOL, whether current_user has permission to share
current_user_can_add_member property - BOOL, whether current_user has permission to share
current_user_has_agreed property - BOOL, whether current_user has permission to share
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
dataset_counts method the number of different datasets that are shared in this group
member_count method None
pending_member_count method None
ENDPOINTS
METHODENDPOINT
POST

/api/label

Create new label object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • if parent_id is set, checks that nominated parent class label is valid, i.e.: that the parent_id exists, is from the same annotation scheme (label_scheme_id) and is not a circular reference to itself (witch can break things). (validate_preprocessor)
  • None (post_auth_preprocessor)

PATCH

/api/label/<id>

Update single label object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • if parent_id is set, checks that nominated parent class label is valid, i.e.: that the parent_id exists, is from the same annotation scheme (label_scheme_id) and is not a circular reference to itself (witch can break things). (validate_preprocessor)
  • checks that the current user has permission to edit this class label. (patch_auth_preprocessor)

GET

/api/label

Get list of label objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, name, color, parent_id, label_scheme_id, id, uuid, is_child, is_parent, created_at, updated_at, is_approved, name_path (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/label/<id>

Get single label object with pk field matching param id

Included fields:
user_id, name, color, parent_id, label_scheme_id, id, uuid, is_child, is_parent, created_at, updated_at, is_approved, name_path, info, info.name, info.value, info.id, label_scheme, label_scheme.id, label_scheme.name, label_scheme.user_id, parent, parent.id, parent.name, user, user.id, user.username, user.last_login, user.first_name, user.last_name, user.active, user.info, user.role, name_path, annotation_count, tags, descendant_count, exemplar_annotation_sets, label_scheme_custodian, current_user_can_edit, current_user_is_custodian (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/label/<id>

Delete single label object with pk field matching param id

Preprocessors:

  • checks that the class label does not have any children or annotations which may be orphaned by delete. (delete_auth_preprocessor)

DELETE

/api/label/<int:id>/tag/<int:tag_id>

None

POST

/api/label/<int:id>/tag/<int:tag_id>

None

GET

/api/label/<int:id>/exemplars

Get list of exemplar images for the label_scheme with the ID matching id. Optionally you can specify an exemplar annontation_set_id if there are more than one for this scheme. If not annotation_set_id is specified. All will be returned. :param id: :param annotation_set_id: :return:

GET

/api/label/<int:id>/exemplars/<int:annotation_set_id>

Get list of exemplar images for the label_scheme with the ID matching id. Optionally you can specify an exemplar annontation_set_id if there are more than one for this scheme. If not annotation_set_id is specified. All will be returned. :param id: :param annotation_set_id: :return:

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
uuid UUID(as_uuid=True) None True True - - A universally unique identifier for this object
name String(length=160) None False False - - The name of this class label
color String(length=10) function True False - - The colour of this class label (hex code, including #)
user_id Integer() None False None - users.id The id of the user who owns or created this class label
label_scheme_id Integer() None False None - label_scheme.id The id of the annotation scheme (label_scheme) containing this class label
parent_id Integer() None True None - label.id id of the parent class label
is_approved Boolean() False True None - - Whether this class label has been approved by the custodian
created_at DateTime() function True None - - Creation time (UTC)
updated_at TIMESTAMP() function True None - - Updated time (UTC)
origin_code String(length=80) None True False - - None
parent_origin_code String(length=80) None True False - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE The user who owns or created this class label
label_scheme label_scheme MANYTOONE The annotation scheme containing this class label
parent label MANYTOONE The parent class label (linked observation)
vocab_elements vocab_element MANYTOMANY A list of vocab_elements linked to this label
children label ONETOMANY None
label_tags label_tags ONETOMANY None
info label_info ONETOMANY None
label_vocab_element label_vocab_element ONETOMANY None
annotations annotation ONETOMANY List of related annotation objects
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property - BOOLEAN, whether or not this class label has a parent class label
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_count method Number of annotations that have been assigned with this label
descendant_count method Number of direct children labels nested under this label
exemplar_annotation_sets method None
label_scheme_custodian method None
tags method List of tags associated with this
current_user_can_edit property None
current_user_is_custodian property None
name_path property None
ENDPOINTS
METHODENDPOINT
POST

/api/label_info

Create new label_info object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/label_info/<id>

Update single label_info object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/label_info

Get list of label_info objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/label_info/<id>

Get single label_info object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/label_info/<id>

Delete single label_info object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False False - - None
value Text() None True None - - None
label_id Integer() None True None - label.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/label_scheme

Create new label_scheme object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/label_scheme/<id>

Update single label_scheme object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Assert object edit permission from shared usergroups. Checks current_user has edit permission. (patch_auth_preprocessor)

GET

/api/label_scheme

Get list of label_scheme objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, description, is_hierarchy, id, name, user, user.username, user.first_name, user.last_name, user.id, tag_files, tag_files.description, tag_files.file_url, tag_files.id, tag_files.name, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_child, parent_label_scheme, parent_label_scheme.id, parent_label_scheme.name, created_at, updated_at, usergroup_count, annotation_set_count, exemplar_annotation_set_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)

GET

/api/label_scheme/<id>

Get single label_scheme object with pk field matching param id

Included fields:
user_id, description, is_hierarchy, id, name, user, user.username, user.first_name, user.last_name, user.id, tag_files, tag_files.description, tag_files.file_url, tag_files.id, tag_files.name, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, is_child, parent_label_scheme, parent_label_scheme.id, parent_label_scheme.name, created_at, updated_at, usergroup_count, annotation_set_count, exemplar_annotation_set_count, parent_label_scheme_ids (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. (get_single_auth_preprocessor)

DELETE

/api/label_scheme/<id>

Delete single label_scheme object with pk field matching param id

Preprocessors:

  • checks that the scheme does not contain annotation sets or children. (delete_preprocessor)
  • Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup (delete_auth_preprocessor)

POST

/api/label_scheme/<int:instance_id>/group/<int:group_id>

Add object with id instance_id to group with id group_id

DELETE

/api/label_scheme/<int:instance_id>/group/<int:group_id>

Remove resource with id instance_id from group with id group_id

GET

/api/label_scheme/<int:label_scheme_id>/labels

None

GET

/api/label_scheme/<int:label_scheme_id>/labels/<int:label_parent_id>

None

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False False - - None
description Text() None True None - - None
user_id Integer() None False None - users.id Foreign key reference for ID of related owner users model
is_hierarchy Boolean() False True None - - None
created_at DateTime() function True None - - Creation time (UTC)
updated_at TIMESTAMP() function True None - - Updated time (UTC)
parent_label_scheme_id Integer() None True None - label_scheme.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE Related owner users model
parent_label_scheme label_scheme MANYTOONE None
annotation_sets annotation_set ONETOMANY None
usergroups groups MANYTOMANY List of groups objects that contain this resource
tag_files label_scheme_file ONETOMANY None
children label_scheme ONETOMANY None
labels label ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property - BOOLEAN, whether or not this class label has a parent class label
is_public property - Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property - Whether or not the currently logged in user is the owner of this object
current_user_is_member property - Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property - Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property - Whether or not the current user has permission to view this object
current_user_can_edit property - Whether or not the current logged in user has edit permission (owner or edit_member)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
annotation_set_count method None
exemplar_annotation_set_count method None
label_count method None
usergroup_count method None
ENDPOINTS
METHODENDPOINT
PATCH

/api/label_scheme_file/<id>

Update single label_scheme_file object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/label_scheme_file

Get list of label_scheme_file objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
description, iscompressed, label_scheme, file_url, label_scheme_id, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/label_scheme_file/<id>

Get single label_scheme_file object with pk field matching param id

Included fields:
description, iscompressed, label_scheme, file_url, label_scheme_id, id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/label_scheme_file/<id>

Delete single label_scheme_file object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/label_scheme_file/<int:fid>/data

Get the data for the file resource matching fid. This endpoint also provides options to manipulate, transform and save data to the database. The querystring takes the following form:

?f={...}&save={...}&disposition=...&template=...
where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition is optional and defines the download type which can be inline (default, displays in the browser) or attachment (triggers a download) , template is optional depending on the output of the steps in f and can be used to define the export format, save is a JSON dictionary that defines batch save operations. This can be used to save the file content or the output of the operations in f to a related database model collection.

POST

/api/label_scheme_file/data

Save file data to database. Use this if it is not possible to dynamically link the file using the file_url or if the file_url is potentially unstable / ephemeral. This should be a multipart form post with file parameter set to the uploaded file and all other fields as in the object definition below.

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
last_save JSON() None True None - - Sequence of file operations performed at last save
name Text() None False False - - The name of the file (optional). Defaults to basename of either file_url or the path of the uploaded file
file_url Text() None True False - - The URL of the file to be loaded dynamically (if data field is not set)
description Text() None True None - - The description of the file (optional)
_rawfiledata LargeBinary() None True None - - The raw file storage for the file. This is not directly accessible through the API
iscompressed Boolean() False True None - - Whether or not the file is compressed or not. If so, it will be automatically decompressed upon access.
label_scheme_id Integer() None False None - label_scheme.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label_scheme label_scheme MANYTOONE None
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property None
ENDPOINTS
METHODENDPOINT
POST

/api/label_tags

Create new label_tags object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/label_tags/<label_id>

Update single label_tags object with pk field matching param label_id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/label_tags

Get list of label_tags objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/label_tags/<label_id>

Get single label_tags object with pk field matching param label_id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/label_tags/<label_id>

Delete single label_tags object with pk field matching param label_id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
label_id Integer() None False None True label.id None
tag_id Integer() None False None True tag.id None
assoc_created_at DateTime() function True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
label label MANYTOONE None
tag tag MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/maplayer

Create new maplayer object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/maplayer/<id>

Update single maplayer object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/maplayer

Get list of maplayer objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/maplayer/<id>

Get single maplayer object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/maplayer/<id>

Delete single maplayer object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=255) None False None - - None
baseurl String(length=255) None False None - - None
layertype String(length=128) None False None - - None
properties JSON(astext_type=Text()) None True None - - None
ENDPOINTS
METHODENDPOINT
POST

/api/media

Create new media object. Expects JSON. Fields shown in MODEL COLUMNS below. In addition to the MODEL COLUMNS below, the JSON body can contain the following parameters: pose: a dict containing parameters for a single pose including associated pose data, poses: a list of dicts as above if linking multiple poses to a single media object (eg: video), media_type: OPTIONAL (default="image"), a string containing the media_type name.

Here are some example payloads for creating media objects:

# example JSON payload for media item with a single pose (eg: still image)
{
    "pose": {"lat":-35.53153264, "lon":150.43962917, "alt":3.558, "dep":28.85, "data":[
        {"name":"temperature","value":16.602},
        {"name":"salinity","value":35.260222}
    ]},
    "key": "PR_20101117_002241_698_LC16",
    "deployment_id": 5,
    "timestamp_start": "2018-06-07T00:47:17.273514"
}

# Same as above, but with dict data { "pose": {"lat":-35.53153264, "lon":150.43962917, "alt":3.558, "dep":28.85, "data":{ "temperature":16.602, "salinity":35.260222 }}, "key": "PR_20101117_002241_698_LC16", "deployment_id": 5, "timestamp_start": "2018-06-07T00:47:17.273514" }

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)

PATCH

/api/media/<id>

Update single media object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to object OWNER only (patch_auth_preprocessor)

Postprocessors:

  • Clears the request cache object for this resource (to cause cache refresh on next request) (_clear_cache)

GET

/api/media

Get list of media objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, timestamp_start, is_valid, key, deployment_id, data, id, media_type, media_type.id, media_type.name, path_best, path_best_thm (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/media/<id>

Get single media object with pk field matching param id

Included fields:
created_at, timestamp_start, is_valid, key, deployment_id, data, id, media_type, media_type.id, media_type.name, path_best, path_best_thm, current_user_can_edit (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

Postprocessors:

  • None (get_single_postprocessor)

DELETE

/api/media/<id>

Delete single media object with pk field matching param id

Preprocessors:

  • None (delete_auth_preprocessor)

GET

/api/media/<int:media_id>/annotations/<int:annotation_set_id>

None

POST

/api/media/save

Media UPLOAD resource.

Used to upload Media to predefined location set out in server config file.

file: file data input containing image file to upload. json: json string containing parameters for new media item

GET

/api/media/<int:id>/thumbnail

Dynamically create thumbnail.

If user is logged in, then they can request different sizes

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
key String(length=80) None False None - - None
path Text() None True None - - None
path_thm Text() None True None - - None
is_valid Boolean() True True None - - None
deployment_id Integer() None False None - deployment.id None
media_type_id Integer() None False None - media_type.id None
timestamp_start DateTime() function True None - - None
created_at DateTime() function True None - - None
parent_id Integer() None True None - media.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
deployment deployment MANYTOONE None
media_type media_type MANYTOONE None
parent media MANYTOONE None
annotations point ONETOMANY List of point objects
poses pose ONETOMANY None
children media ONETOMANY None
media_collection_media media_collection_media ONETOMANY None
events deployment_event ONETOMANY None
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
media_collections media_collection media_collection_media Proxy attribute that presents the linked media_collection objects from the media_collection_media collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_child property - BOOLEAN, whether or not this has a parent
data property - JSON data containing optional properties for this resource
distance method lat, lon FLOAT, distance (in meters) of closest linked pose relative to lat and lon (which are both in decimal degrees)
timestamp_proximity method ts Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
current_user_can_edit method Whether or not the current user owns the deployment and can edit this media item
event_log method None
path_best property None
path_best_thm property None
pose property The first pose from related poses or if child media item, it gets the closest matching pose from the parent_media item based on timestamp_start
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection

Create new media_collection object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/media_collection/<id>

Update single media_collection object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Assert object edit permission from shared usergroups. Checks current_user has edit permission. (patch_auth_preprocessor)

GET

/api/media_collection

Get list of media_collection objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name, parent_collection_id, description, user, created_at, children, user.id, user.first_name, user.last_name, user.username, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, usergroup_count (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view (get_many_auth_preprocessor)

GET

/api/media_collection/<id>

Get single media_collection object with pk field matching param id

Included fields:
id, name, parent_collection_id, description, user, created_at, children, user.id, user.first_name, user.last_name, user.username, current_user_can_view, current_user_is_owner, current_user_is_member, current_user_can_edit, is_public, usergroup_count, media_count, data (see below for more details)

Preprocessors:

  • Assert object view permission from shared usergroups. Checks current_user has view permission. (get_single_auth_preprocessor)

DELETE

/api/media_collection/<id>

Delete single media_collection object with pk field matching param id

Preprocessors:

  • Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup (delete_auth_preprocessor)

POST

/api/media_collection/<int:instance_id>/group/<int:group_id>

Add instance with ID of instance_id to the group with the ID group_id

DELETE

/api/media_collection/<int:instance_id>/group/<int:group_id>

Remove instance with ID of instance_id from the group with the ID group_id

GET

/api/media_collection/<int:id>/export

Export media collection from media_collection matching id. Search queries are executed on the media model.

Querystring parameters are:

?q={...}&f={...}&disposition=...&template=...&include_columns=[...]

Where q is a JSON search query (see Making API search queries) on the collection model, where f is a JSON dictionary containing a sequence of operations for transforming the data (see Data transformation API for more info), disposition defines the download type which can be attachment (default, triggers a download) or inline (displays in the browser), template is optional depending on the output of the steps in f and can be used to define the export format, include_columns is a JSON list of column fields for the exported model. Nested fields for related models delimited with a . If include_columns is omitted, all allowed columns will be returned.

Metadata for the annotation_set matching id is also returned in the response. Depending on the output format, this could be as part of the response body in a metadata field or in the response headers with the key X-Content-Metadata.

Allowed columns include: id, key, timestamp_start, path_best, path_best_thm, pose.timestamp, pose.lat, pose.lon, pose.alt, pose.dep, pose.data, pose.id, deployment.key, deployment.campaign.key, deployment.id, deployment.campaign.id, event_log

# Example1:
/api/media_collection/1776/export?template=dataframe.csv&f={"operations": [{"module": "pandas", "method": "json_normalize"}]}

NB: the UI contains an "ADVANCED" option which can help build more complex export queries.

GET

/api/media_collection/<int:media_collection_id>/media

Get list of media objects contained in the media_collection with an ID matching media_collection_id. Accepts search query parameters. See Making API search queries for instructions on making search queries

POST

/api/media_collection/<int:media_collection_id>/media

Add media objects matching the search query defined in the json post parameter q to the media_collection with an ID matching media_collection_id. q is a search query in the format defined in Making API search queries section and is sent as either a URL parameter or form post parameter. Request returns the corresponding media_collection.

GET

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Get the single media object with the ID media_id from the media_collection with the ID media_collection_id

POST

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Add the media object with the ID media_id to the media_collection with the ID media_collection_id

DELETE

/api/media_collection/<int:media_collection_id>/media/<int:media_id>

Remove the media object with the ID media_id from the media_collection with the ID media_collection_id

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
name String(length=80) None False None - - The name of the media_collection
description Text() None True None - - A concise description of the media_collection
parent_collection_id Integer() None True None - media_collection.id A reference to the ID of a parent media_collection
created_at DateTime() function False None - - The creation date-time
user_id Integer() None True None - users.id Foreign key reference for ID of related owner users model
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
parent media_collection MANYTOONE The parent media_collection instance
media media MANYTOMANY A list of media contained in this media_collection
user users MANYTOONE Related owner users model
usergroups groups MANYTOMANY List of groups objects that contain this resource
annotation_sets annotation_set ONETOMANY None
children media_collection ONETOMANY A list of childen media_collections that belong to this one
media_collection_media media_collection_media ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_public property - Whether or not this object is public (i.e. shared in a public group)
current_user_is_owner property - Whether or not the currently logged in user is the owner of this object
current_user_is_member property - Whether or not the current logged in user is a member of a group that includes this object
current_user_is_edit_member property - Whether or not the current logged in user is a member with edit permission of a group that includes this object
current_user_can_view property - Whether or not the current user has permission to view this object
current_user_can_edit property - Whether or not the current logged in user has edit permission (owner or edit_member)
data property - JSON data containing optional properties for this resource
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
media_count method None
usergroup_count method None
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection_media

Create new media_collection_media object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (edit_auth_preprocessor)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/media_collection_media

Get list of media_collection_media objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, media_id, media_collection_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/media_collection_media/<media_collection_id>

Get single media_collection_media object with pk field matching param media_collection_id

Included fields:
created_at, media_id, media_collection_id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/media_collection_media/<media_collection_id>

Delete single media_collection_media object with pk field matching param media_collection_id

Preprocessors:

  • None (edit_auth_preprocessor)
  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
media_id Integer() None False None True media.id None
media_collection_id Integer() None False None True media_collection.id None
created_at DateTime() function False None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE None
media_collection media_collection MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/media_type

Create new media_type object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/media_type

Get list of media_type objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/media_type/<id>

Get single media_type object with pk field matching param id

Included fields:
id, name (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/media_type/<id>

Delete single media_type object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - The name of the media type
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media ONETOMANY None
ENDPOINTS
METHODENDPOINT
POST

/api/platform

Create new platform object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/platform/<id>

Update single platform object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/platform

Get list of platform objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, description, id, name, reference, user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/platform/<id>

Get single platform object with pk field matching param id

Included fields:
created_at, description, id, name, reference, user_id, datasources, data (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/platform/<id>

Delete single platform object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
name String(length=80) None False None - - None
key String(length=80) None False True - - None
description Text() None True None - - None
reference Text() None True None - - None
user_id Integer() None True None - users.id None
created_at DateTime() function False None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
deployments deployment ONETOMANY None
datasources datasource ONETOMANY None
layers platform_maplayer ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
data property - JSON data containing optional properties for this resource
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
current_user_is_owner method None
ENDPOINTS
METHODENDPOINT
POST

/api/platform_maplayer

Create new platform_maplayer object. Expects JSON. Fields shown in MODEL COLUMNS below. A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance's class are allowed. These could be, for example, any mapped columns or relationships.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/platform_maplayer/<id>

Update single platform_maplayer object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/platform_maplayer

Get list of platform_maplayer objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/platform_maplayer/<id>

Get single platform_maplayer object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/platform_maplayer/<id>

Delete single platform_maplayer object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=255) None False None - - None
baseurl String(length=255) None False None - - None
layertype String(length=128) None False None - - None
minzoom Integer() None True None - - None
properties JSON(astext_type=Text()) None True None - - None
platform_id Integer() None True None - platform.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
platform platform MANYTOONE None
ENDPOINTS
METHODENDPOINT
PATCH

/api/point/<id>

Update single point object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (patch_auth_preprocessor)

GET

/api/point

Get list of point objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
media_id, annotation_set_id, t, x, y, supplementary_annotations, data, id, timestamp, annotations, annotations.id, annotations.annotation_set_id (see below for more details)

Preprocessors:

  • Filter results based on permissions from parent annotation_set (get_many_auth_preprocessor)

GET

/api/point/<id>

Get single point object with pk field matching param id

Included fields:
media_id, annotation_set_id, t, x, y, supplementary_annotations, data, id, timestamp, annotations, annotations.id, annotations.annotation_set_id (see below for more details)

Preprocessors:

  • None (get_single_auth_preprocessor)

Postprocessors:

  • None (get_single_postprocessor)

DELETE

/api/point/<id>

Delete single point object with pk field matching param id

Preprocessors:

  • None (delete_auth_preprocessor)

POST

/api/point

Custom post endpoint

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
data_json Text() None True None - - Text field containing JSON properties for this resource
x Float(precision=53) None True False - - X location of point as a proportion across the frame width (0-1.0) or latitude for map objects
y Float(precision=53) None True False - - Y location of point as a proportion across the frame height (0-1.0) or longitude for map objects
t Float(precision=53) None True False - - Number of seconds of annotation relative to media.start_time (eg: for video)
media_id Integer() None False None - media.id Foreign key id of media object linked to point
annotation_set_id Integer() None False None - annotation_set.id Foreign key id of the parent/origin annotation_set. I.e.: the one linked to the initial creation of the point
updated_at TIMESTAMP() function True None - - Updated time (UTC)
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE Related media object
annotation_set annotation_set MANYTOONE Parent/origin annotation_set object
annotations annotation ONETOMANY List of annotation objects
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
timestamp property - The in-situ timestamp for when the annotated object was captured/sampled in the media frame. Returns media.timestamp_start + t if t is set, otherwise it just returns media.timestamp_start
has_xy property - BOOLEAN, whether or not the point has x-y coordinates. If false, it is a whole-frame annotation, not a point annotation
data property - JSON data containing optional properties for this resource
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
pose property Get closest linked pose to timestamp
ENDPOINTS
METHODENDPOINT
POST

/api/pose

Create new pose object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/pose

Get list of pose objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, deployment_id, dep, alt, lat, lon, events, timestamp, deployment, deployment.user_id, deployment.name, deployment.created_at, deployment.campaign_id, deployment.key, deployment.id, data, media, media.key, media.id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/pose/<id>

Get single pose object with pk field matching param id

Included fields:
id, deployment_id, dep, alt, lat, lon, events, timestamp, deployment, deployment.user_id, deployment.name, deployment.created_at, deployment.campaign_id, deployment.key, deployment.id, data, media, media.key, media.id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/pose/<id>

Delete single pose object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
lat Float(precision=53) None True False - - None
lon Float(precision=53) None True False - - None
alt Float() None True False - - None
dep Float() None True False - - None
timestamp DateTime() function False None - - None
media_id Integer() None False None - media.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
media media MANYTOONE None
_data posedata ONETOMANY None
events deployment_event ONETOMANY None
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
distance method lat, lng FLOAT, distance (in meters) to lat and lon (which are both in decimal degrees)
timestamp_proximity method ts Absolute difference in seconds of the in-situ timestamp and input ts, which is datetime string eg: "2020-09-25T00:57:11.945009" (or in a format that is parsable by dateutil.parser.parse)
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
data property Properties for related pose item including any linked posedata fields
ENDPOINTS
METHODENDPOINT
POST

/api/posedata

Create new posedata object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

GET

/api/posedata

Get list of posedata objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/posedata/<id>

Get single posedata object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/posedata/<id>

Delete single posedata object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - None
value Float() None True False - - None
pose_id Integer() None False None - pose.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
pose pose MANYTOONE None
ENDPOINTS
METHODENDPOINT
POST

/api/roles

Create new roles object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/roles/<id>

Update single roles object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/roles

Get list of roles objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/roles/<id>

Get single roles object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/roles/<id>

Delete single roles object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False True - - None
ENDPOINTS
METHODENDPOINT
POST

/api/tag

Create new tag object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • None (post_preprocessor)
  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/tag/<id>

Update single tag object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/tag

Get list of tag objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
user_id, name, type_id, synonym_tag_id, type, id, is_synonym, type, synonyms, synonyms.name, synonyms.id, synonyms.user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/tag/<id>

Get single tag object with pk field matching param id

Included fields:
user_id, name, type_id, synonym_tag_id, type, id, is_synonym, type, synonyms, synonyms.name, synonyms.id, synonyms.user_id (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/tag/<id>

Delete single tag object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False None - - None
user_id Integer() None False None - users.id None
type_id Integer() None True None - tag_type.id None
description Text() None True None - - None
synonym_tag_id Integer() None True None - tag.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
type tag_type MANYTOONE None
synonym_tag tag MANYTOONE None
synonyms tag ONETOMANY None
label_tags label_tags ONETOMANY None
annotation_tags annotation_tags ONETOMANY Collection of annotation_tags associations
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
labels label label_tags Proxy attribute that presents the linked label objects from the label_tags collection
HYBRID ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results and support both query and instance property operations. HYBRID ATTRIBUTES can be used when building filters (for endpoints that support filtering, see Making API queries ). Note HYBRID METHODS may require input parameters.
NAME TYPE ARGS DESCRIPTION
is_synonym property - None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_type

Create new tag_type object. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/tag_type/<id>

Update single tag_type object with pk field matching param id. Expects JSON. Fields shown in MODEL COLUMNS below.

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/tag_type

Get list of tag_type objects matching API query. See Making API search queries for instructions on making search queries

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/tag_type/<id>

Get single tag_type object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/tag_type/<id>

Delete single tag_type object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
name String(length=80) None False True - - None
description Text() None True None - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
tags tag ONETOMANY None
ENDPOINTS
METHODENDPOINT
GET

/api/usergroups

Get list of usergroups objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
created_at, approved, can_edit, added_by_user, added_by_user.id, added_by_user.first_name, added_by_user.last_name, user, user.id, user.username, user.created_at, user.last_login, user.first_name, user.last_name, user.active, user.is_admin, group, group.id, group.name, can_add_members, can_share_data, has_agreed, group.is_public, group.is_restricted, group.user_id, group.requires_approval, group.requires_agreement, group.group_type_id, group.groupinfo, group.created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/usergroups/<group_id>

Get single usergroups object with pk field matching param group_id

Included fields:
created_at, approved, can_edit, added_by_user, added_by_user.id, added_by_user.first_name, added_by_user.last_name, user, user.id, user.username, user.created_at, user.last_login, user.first_name, user.last_name, user.active, user.is_admin, group, group.id, group.name, can_add_members, can_share_data, has_agreed, group.is_public, group.is_restricted, group.user_id, group.requires_approval, group.requires_agreement, group.group_type_id, group.groupinfo, group.created_at (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
user_id Integer() None False None True users.id None
group_id Integer() None False None True groups.id None
created_at DateTime() function True None - - None
approved Boolean() False True None - - None
can_edit Boolean() False True None - - None
can_add_members Boolean() False True None - - None
can_share_data Boolean() False True None - - None
has_agreed Boolean() False True None - - None
added_by_user_id Integer() None True None - users.id None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
user users MANYTOONE None
added_by_user users MANYTOONE None
group groups MANYTOONE None
ENDPOINTS
METHODENDPOINT
GET

/api/users

Get list of users objects matching API query. See Making API search queries for instructions on making search queries

Included fields:
id, user_created_at, last_login, first_name, last_name, username, active, info, role, affiliations, affiliations.name, affiliations.groupinfo, affiliations.id, affiliations_names (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/users/<id>

Get single users object with pk field matching param id

Included fields:
id, user_created_at, last_login, first_name, last_name, username, active, info, role, affiliations, affiliations.name, affiliations.groupinfo, affiliations.id, affiliations_names (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

Postprocessors:

  • None (get_single_postprocessor)

DELETE

/api/users/<id>

Delete single users object with pk field matching param id

Preprocessors:

  • Restrict request to ADMIN user only (assert_current_user_is_admin)
  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/users/api_token

Manage API token

PATCH

/api/users/api_token

Manage API token

DELETE

/api/users/api_token

Manage API token

POST

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership

DELETE

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership

PATCH

/api/users/<int:user_id>/group/<int:group_id>

Manage group membership

POST

/api/users/login

Log in. Requires form parameters username and password.

DELETE

/api/users/login

Log out the current session

POST

/api/users

Update user information

PATCH

/api/users/<int:user_id>

Update user information

POST

/api/users/reset_password

None

GET

/api/users/reset_password

None

POST

/api/users/reset_password/<token>

None

GET

/api/users/reset_password/<token>

None

POST

/api/users/<int:user_id>/email

Send an email to the user. Requires json post body containing message and optionally subject. If no subject, default subject will be "User message from PROJECT_NAME"

MODEL COLUMNS FILTERABLE
These attributes map to database columns and can be used when building filters (for endpoints that support filtering, see Making API queries )
NAME TYPE DEFAULT NULLABLE UNIQUE PRIM_KEY FORGN_KEY DESCRIPTION
id Integer() None False None True - Primary key id
username String(length=80) None False True - - None
email String(length=80) None False True - - None
password String(length=128) None False None - - None
created_at DateTime() function False None - - None
last_login DateTime() now() True None - - None
first_name String(length=30) None False None - - None
last_name String(length=30) None False None - - None
active Boolean() True True None - - None
is_admin Boolean() False True None - - None
info Text() None True None - - None
role_id Integer() None True None - roles.id None
api_token String(length=80) None True True - - None
RELATED MODELS FILTERABLE
These attributes expose related objects. Relations can either be single elements or a collection of elements. Related models can be used to contruct filters (for endpoints that support filtering, see Making API queries )
FIELD RELATION DIRECTION DESCRIPTION
role roles MANYTOONE None
affiliations_usergroups usergroups ONETOMANY None
usergroups usergroups ONETOMANY None
ASSOCIATION PROXIES FILTERABLE
These attributes map linked objects from collections (eg: many-to-many relationships that have an association table) Association proxies can be used when building filters (for endpoints that support filtering, see Making API queries )
ATTRIBUTE MODEL COLLECTION DESCRIPTION
affiliations group affiliations_usergroups Proxy attribute that presents the linked group objects from the affiliations_usergroups collection
OTHER MODEL ATTRIBUTES FILTERABLE
These are special defined attributes return dynamically processed results. These attributes do not work in filter queries.
NAME TYPE DESCRIPTION
affiliations_names method None
full_name method None
get_id method None
is_active method None
is_anonymous method None
is_authenticated method None

Making API queries

Pagination

/api/resource?results_per_page=...&page=...

Responses to most GET requests (with the exception of the export endpoints) are paginated by default, with at most ten objects per page. To request a specific page, add a page=N query parameter to the request URL, where N is a positive integer (the first page is page one). If no page query parameter is specified, the first page will be returned.

In order to specify the number of results per page, add the query parameter results_per_page=N where N is a positive integer. If results_per_page is greater than the maximum number of results per page as configured by the server, then the query parameter will be ignored.

In addition to the "objects" list, the response JSON object will have a "page" key with the current page number, a "num_pages" key with total number of pages into which the set of matching instances is divided, and a "num_results" key with total number of instances which match the requested search.

Query format:

/api/resource?q={"filters":[...],"limit":...,"offset":...,"order_by":[...],"group_by":[...],"single":...}

The query parameter q must be a JSON string. It can have the following mappings, all of which are optional:

filters

A list of <filterobjects> of one of the following forms:

{"name": <fieldname>, "op": <operatorname>, "val": <argument>}

Where <operatorname> is one of the strings described below, <argument> is a value to be used as the second argument to the given operator and <fieldname> is the name of the field of the model to which to apply the operator, which can be either a MODEL COLUMN, RELATED MODEL, ASSOCIATION PROXY or HYBRID ATTRIBUTE for a resource.

{"name": <fieldname>, "op": <operatorname>, "field": <fieldname>}

Where the first <fieldname> and <operatorname> are as above and the second <fieldname> is the field of the model that should be used as the second argument to the operator.

The first <fieldname> may specify a field on a related model, if it is a string of the form <relationname>__<fieldname>. Alternatively if the field name is the name of a relation and the operator is "has" or "any", the "val" argument can be a dictionary with the arguments representing another, nested filter to be applied as the argument for "has" or "any".

The <operatorname> strings recognized by the API incude:

  • ==, eq, equals, equals_to
  • !=, neq, does_not_equal, not_equal_to
  • >, gt, <, lt
  • >=, ge, gte, geq, <=, le, lte, leq
  • in, not_in
  • is_null, is_not_null
  • like, ilike
  • has
  • any

TIP: use the has and any operators to search for instances by fields on related instances. In general, use the any operator if the relation is a list of objects (i.e.: ONETOMANY/MANYTOMANY) and use the has operator if the relation is a single object (i.e.: MANYTOONE).

Filters can also exclude results, for example:

{"not": <filterobject>}

Filter objects can also be arbitrary Boolean formulas, for example:

{"or": [<filterobject>, {"and": [<filterobject>, ...]}, ...]}

Filter objects can also be defined on Hybrid Attributes of a model. hybrid property filter objects are defined in the same way as column fields, but to filter by a hybrid method with one or more input arguments (<arg1>,<arg2>,...<argN>), the object can be defined as:

{"name": {"method":<method_name>,"args":[<arg1>,<arg2>,...<argN>]}, "op": <operatorname>, "val": <argument>}

The returned list of matching instances will include only those instances that satisfy all of the given filters.

If a filter is poorly formatted (for example, op is set to '==' but val is not set), the server responds with 400 Bad Request.

limit
A positive integer which specifies the maximum number of objects to return.
offset
A positive integer which specifies the offset into the result set of the returned list of instances.
order_by

A list of objects of the form:

{"field": <fieldname>, "direction": <directionname>}

where <fieldname> is a string corresponding to the name of a field of the requested model and <directionname> is either "asc" for ascending order or "desc" for descending order.

<fieldname> may alternately specify a field on a related model, if it is a string of the form <relationname>__<fieldname>.

Ordering can also be defined on Hybrid Attributes of a model. hybrid property order_by objects are defined in the same way as column fields, but to filter by a hybrid method with one or more input arguments (<arg1>,<arg2>,...<argN>), the object can be defined as:

{"field": {"method":<method_name>,"args":[<arg1>,<arg2>,...<argN>]}, "direction": <directionname>}
group_by

A list of objects of the form:

{"field": <fieldname>}

where <fieldname> is a string corresponding to the name of a field of the requested model.

<fieldname> may alternately specify a field on a related model, if it is a string of the form <relationname>__<fieldname>.

single
A Boolean representing whether a single result is expected as a result of the search. If this is true and either no results or multiple results meet the criteria of the search, the server responds with an error message.

Data transformation and batch operations

/api/resource?f={...}&save={...}

Some endpoints support data transformation and manipulation of the output using the data transformation API. This allows users to define a sequence of operations that can be used to transform the output of the response in order to (i) export data in a desired format or (ii) perform batch import operations.

DOCUMENTATION FOR THIS IS STILL COMING... WATCH THIS SPACE...

Other resources