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, likelihood, needs_review, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, 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, likelihood, needs_review, point.id, tags, tags.id, tags.name, comment, timestamp, parent_id, color, suggested_tags, object_id, label_id, point.updated_at, observation_count (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.

TRANSLATING TO OTHER LABEL_SCHEMES

When using group_by=label it is possible translate labels from a source to a target label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required. When passing translation parameters, there will the following additional output columns: label_lineage_names, translated_id, translated_lineage_names, translated_name, translated_label_scheme_name, translated_info.

# 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

# Example: tally of annotations by top 100 labels for a give deployment (id=10306) returned as an HTML table # Translated into the catami annotation scheme (id=2) using the "caab" and "worms" vocab_registries (only works with compatible schemas) /api/annotation/tally/label?q={"filters":[{"name":"point","op":"has","val":{"name":"media","op":"has","val":{"name":"deployment_id","op":"eq","val":10306}}}]}&results_per_page=100&unannotated_point_count=294&translate={"vocab_registry_keys":["caab","worms"],"target_label_scheme_id":"2"}&template=data.html

# Example: tally annotations by label in a deployment matching the key "r20200131_021337_NG02_middleton_22", filtered for occurrences between 20-30m, showing only primary observation (no linked children, i.e. only count an observation group/object once) /api/annotation/tally/label?q={"filters":[{"name":"point","op":"has","val":{"name":"media","op":"has","val":{"name":"deployment","op":"has","val":{"name":"key","op":"eq","val":"r20200131_021337_NG02_middleton_22"}}}},{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"poses","op":"any","val": {"name":"dep","op":"gt","val":20}}}},{"name":"point","op":"has","val": {"name":"media","op":"has","val": {"name":"poses","op":"any","val": {"name":"dep","op":"lt","val":30}}}},{"name":"is_child","op":"eq","val":false}]}

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)

likelihood Float() 1.0 True None - -

(Optional) likelihood/probability of the label assignment

needs_review Boolean() False True None - -

Whether or not this annotation requires review

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: ID of primary observation (parent annotation) if linked, otherwise own ID.

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, is_full_bio_score, is_real_science, is_qaqc, is_final, 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, is_full_bio_score, is_real_science, is_qaqc, is_final, 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. This endpoint also supports translating to a target label_scheme (when possible)

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 fields include:

id, tag_names, comment, label.id, label.name, label.lineage_names, label.uuid, updated_at, user.username, needs_review, 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.id, point.media.deployment.key, point.media.deployment.name, point.media.deployment.campaign.id, point.media.deployment.campaign.key, point.media.deployment.campaign.name, object_id, label.translated.id, label.translated.name, label.translated.lineage_names, label.translated.uuid, label.translated.translation_info

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

TRANSLATING TO OTHER LABEL_SCHEMES

This endpoint also supports the translation of labels from a source to a target label_scheme. another label_scheme using the semantic translation framework. In order to do this, you need to specify the additional translate url query parameter:

&translate={"target_label_scheme_id":..., "vocab_registry_keys": ..., "mapping_override": ...}
Where target_label_scheme_id [required] is an INT with the id of the target label scheme, vocab_registry_keys [optional] is a list containing the priority order of keys for vocab_registries for which to perform the semantic translation and mapping_override defines a set of key-value pairs containing source label.id : target label.id for which to override the translation. Note: for extended schemes, labels are translated through tree_traversal and no semantic translation is required.

NOTE: you also need to add the label.translated.* columns to obtain the translation output. These columns are ignored if no translate query parameter is supplied.

EXAMPLES

# 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

POST

/api/annotation_set/<int:annotation_set_id>/clone

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

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

is_full_bio_score Boolean() False True None - -

whether or not the intent was full biodiversity scoring, or just targeted scoring

is_real_science Boolean() False True None - -

whether or not this is for science, or was for education / training / testing

is_qaqc Boolean() False True None - -

whether or not the annotation set has been QA/QC'd

is_final Boolean() False True None - -

whether or not the annotator has completed annotating

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
GET

/api/datasource_type

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

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

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/datasource_type/<id>

Get single datasource_type object with pk field matching param id

Included fields:
id, name, 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
id Integer() None False None True -

Primary key id

name String(length=80) None False True - -

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
datasources datasource 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() False 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, origin_code, parent_origin_code, name_path, lineage (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, origin_code, parent_origin_code, name_path, lineage, 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, 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

is_mapped property -

BOOLEAN, whether this label has one or more vocab_element mappings

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

translated property

Special API property returns label object in target label scheme. Requires translate query parameter containing target_label_scheme_id and optional vocab_registry_keys parameters. See Label Translation for more information.

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, label_scheme_files, label_scheme_files.description, label_scheme_files.file_url, label_scheme_files.id, label_scheme_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, label_scheme_files, label_scheme_files.description, label_scheme_files.file_url, label_scheme_files.id, label_scheme_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

PATCH

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

Reset labels parents for label_scheme with id matching label_scheme_id. Uses origin_code and parent_origin_code to match up labels. Accepts optional query string argument replace_existing=true, which will reset parent_ids for labels that are already set. By default this is set to false

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

label_scheme_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
POST

/api/label_scheme_file

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

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

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, last_save (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, last_save (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

has_unlabeled_annotations method annotation_set_id

BOOL, whether or not the media object contains unlabeled annotations from the annotation_set with the id annotation_set_id

has_annotations method annotation_set_id

BOOL, whether or not the media object contains any annotations from the annotation_set with the id annotation_set_id

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

set_label property

SPECIAL SETTER PROPERTY! Returns None, but is used to set a label based on lookup condition / parameters. Parameters are passed by scalar value with query string properties or by setting value as dict. The property value can be scalar, dict, list of dicts or list of scalars.

Option 1: setting by dict

point.set_label = {"filters":[{"name":...,"op":...,"val":...}],"comment":...,"likelihood":...,"needs_review":...}
# OR for multiple
point.set_label = [{"filters":[{"name":...,"op":...,"val":...}],"comment":...,"likelihood":...,"needs_review":...}, ...]
where comment, likelihood and needs_review are optional and filters is a list of filter objects for the label resource. See Making API search queries.

Option 2: setting with QS params

point.set_label = 'ORIGIN_CODE1'
# OR for multiple
point.set_label = ['ORIGIN_CODE1', 'ORIGIN_CODE2']

# with query string parameters &set_label_field_name=origin_code&set_label_field_op="eq"

where the set_label_field_name denotes the field name to filter for the supplied value and set_label_field_op denotes the operation to use for matching, which can be either eq (default) or ilike for exact or case insensitive similar matching, respectively.

Option 2 is useful for setting labels using import tools from CSV files. See TODO section for more.

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

ENDPOINTS
METHODENDPOINT
POST

/api/vocab_element

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

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/vocab_element/<id>

Update single vocab_element 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/vocab_element

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

Included fields:
id, name, key, parent_key, vocab_registry, vocab_registry.key, vocab_registry.vocab_element_key_name, vocab_registry.name, vocab_registry.description, created_at, updated_at, user, user.id, lineage, user.first_name, mapped_registries, user.last_name, other_names, other_names.id, other_names.name, origin_updated_at, reference_url, reference_url_parent (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/vocab_element/<id>

Get single vocab_element object with pk field matching param id

Included fields:
id, name, key, parent_key, vocab_registry, vocab_registry.key, vocab_registry.vocab_element_key_name, vocab_registry.name, vocab_registry.description, created_at, updated_at, user, user.id, lineage, user.first_name, mapped_registries, user.last_name, other_names, other_names.id, other_names.name, origin_updated_at, reference_url, reference_url_parent, data, description, mapped_labels (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/vocab_element/<id>

Delete single vocab_element object with pk field matching param id

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/vocab_element/<registry_key>/<element_key>

None

POST

/api/vocab_element/<registry_key>/<element_key>

None

PATCH

/api/vocab_element/<registry_key>/<element_key>

None

POST

/api/vocab_element/<registry_key>/<element_key>/label/<label_id>

None

DELETE

/api/vocab_element/<registry_key>/<element_key>/label/<label_id>

None

GET

/api/vocab_element/nested

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=128) None False False - -

None

key String(length=96) None False None - -

None

lineage JSON() None True None - -

None

data JSON() None True None - -

None

mapped_registries JSON() None True None - -

None

description Text() None True None - -

None

parent_key String(length=96) None True None - -

None

vocab_registry_key String(length=96) None False None - vocab_registry.key

The id of the vocab_registry

user_id Integer() None False None - users.id

The id of the user who created and owns this record

created_at DateTime() function True None - -

None

updated_at TIMESTAMP() function True None - -

Updated time (UTC)

origin_updated_at DateTime() 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
vocab_registry vocab_registry MANYTOONE

The vocab_registry that contains this vocab_element

user users MANYTOONE

The user who owns or created and owns this record

labels label MANYTOMANY

A list of labels linked to this vocab_element

other_names vocab_element_names ONETOMANY

None

label_vocab_element label_vocab_element 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
mapped_labels method

None

reference_url method

None

reference_url_parent method

None

ENDPOINTS
METHODENDPOINT
POST

/api/vocab_element_names

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

Preprocessors:

  • Restrict request to LOGGED IN users only (post_auth_preprocessor)

PATCH

/api/vocab_element_names/<id>

Update single vocab_element_names 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/vocab_element_names

Get list of vocab_element_names 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/vocab_element_names/<id>

Get single vocab_element_names object with pk field matching param id

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/vocab_element_names/<id>

Delete single vocab_element_names 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 False - -

None

vocab_element_id Integer() None False None - vocab_element.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
vocab_element vocab_element MANYTOONE

None

ENDPOINTS
METHODENDPOINT
POST

/api/vocab_registry

Create new vocab_registry 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/vocab_registry/<key>

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

Preprocessors:

  • Restrict request to OWNER only (patch_auth_preprocessor)

GET

/api/vocab_registry

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

Included fields:
key, name, description, created_at, updated_at, user, user.id, user.first_name, user.last_name, vocab_element_key_name, registry_urls (see below for more details)

Preprocessors:

  • Allow all requests (get_many_auth_preprocessor)

GET

/api/vocab_registry/<key>

Get single vocab_registry object with pk field matching param key

Included fields:
key, name, description, created_at, updated_at, user, user.id, user.first_name, user.last_name, vocab_element_key_name, registry_urls (see below for more details)

Preprocessors:

  • Allow all requests (get_single_auth_preprocessor)

DELETE

/api/vocab_registry/<key>

Delete single vocab_registry object with pk field matching param key

Preprocessors:

  • Restrict request to OWNER only (delete_auth_preprocessor)

GET

/api/vocab_registry/<key>/match

None

GET

/api/vocab_registry/<key>/get_element

None

GET

/api/vocab_registry/<key>/get_all_elements

None

GET

/api/vocab_registry/<key>/get_children

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
key String(length=96) None False True True -

None

name String(length=128) None False True - -

None

module String(length=96) None False None - -

None

module_kwargs JSON() None True None - -

None

vocab_element_key_name String(length=96) None True None - -

None

description Text() None True None - -

None

user_id Integer() None False None - users.id

The id of the user who created and owns this record

created_at DateTime() function True None - -

None

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
user users MANYTOONE

The user who owns or created and owns this record

vocab_elements vocab_element 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
registry_urls method

None

registry_plugin property

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