API reference

IMPORTANT: STILL UNDER CONSTRUCTION! The endpoints, columns and related models are real and auto-generated from the code, but the descriptions / summaries should be completely ignored - it may do more harm than good if you attempt to read them! 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:
post_auth_preprocessor(): Enforce implied permissions from parent annotation_set
assert_user_login(): Restrict request to logged in users only
GET

/api/annotation

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

Included fields:
id , created_at , updated_at , annotation_set_id , data , tag_group , tag_group.id , tag_group.name , tag_group.uuid , tag_group.parent_id , tag_group.tag_scheme_id , media_annotation , media_annotation.media_id , media_annotation.x , media_annotation.y , media_annotation.t , media_annotation.data , media_annotation.annotation_set_id , media_annotation.id , tags , tags.id , tags.name , comment (see below for more details)
Included methods:
color() , suggested_tags()
Preprocessors:
view_many_not_allowed_preprocessor(): GET_MANY is not allowed. THIS ENDPOINT IS RESTRICTED.
GET

/api/annotation/<int:id>

Get single annotation object with id field matching param id

Included fields:
id , created_at , updated_at , annotation_set_id , data , tag_group , tag_group.id , tag_group.name , tag_group.uuid , tag_group.parent_id , tag_group.tag_scheme_id , media_annotation , media_annotation.media_id , media_annotation.x , media_annotation.y , media_annotation.t , media_annotation.data , media_annotation.annotation_set_id , media_annotation.id , tags , tags.id , tags.name , comment (see below for more details)
Included methods:
color() , suggested_tags()
Preprocessors:
view_auth_preprocessor(): Enforce implied permissions from parent annotation_set
DELETE

/api/annotation/<int:id>

Delete single annotation object with id field matching param id

Preprocessors:
edit_auth_preprocessor(): Enforce implied permissions from parent annotation_set
assert_user_is_owner(): Restrict request to object OWNER only
PATCH

/api/annotation

AnnotationLabel PATCH resource. Annotation Label PATCH MANY. For setting multiple labels at once. :param URL: int: id: ID of annotation_set :param GET: json: q: restless search query :param GET: int: tag_group_id: ID of tag group to set :param GET: int: tag_id: [OPTIONAL] ID of tag to append to list of tags already set by tag_group_id :returns PATCH: json: result of query

PATCH

/api/annotation/<int:id>

None
DELETE

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

None
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
tag_group_id INTEGER None True None False Foreign key id for related tag_group (or class label)
created_at DATETIME function True None False Creation time (UTC)
updated_at TIMESTAMP function True None False Updated time (UTC)
user_id INTEGER None False None False Foriegn key id for owner user object
media_annotation_id INTEGER None False None False Foriegn key id for media_annotation object
annotation_set_id INTEGER None False None False Foriegn key id for annotation_set object
comment TEXT None True None False User comment
RELATED MODELS
FIELD RELATION DESCRIPTION
tag_group tag_group Related tag_group object
user users Related owner user object
media_annotation media_annotation Related media_annotation object
annotation_set annotation_set Related annotation_set object
annotationtags annotation_tags None
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_set

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/annotation_set/<int:id>

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

Preprocessors:
patch_auth_preprocessor(): Assert object edit permission from shared usergroups. Checks current_user has edit permission.
assert_user_login(): Restrict request to logged in users only
GET

/api/annotation_set

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

Included fields:
id , name , parent_annotation_set_id , description , user , user.id , user.email , user.full_name , user.first_name , user.last_name , created_at , children , media_collection , media_collection.id , media_collection.name , tag_scheme , tag_scheme.id , tag_scheme.name , annotation_count , data , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
annotation_count() , usergroup_count()
Preprocessors:
get_many_auth_preprocessor(): Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view
GET

/api/annotation_set/<int:id>

Get single annotation_set object with id field matching param id

Included fields:
id , name , parent_annotation_set_id , description , user , user.id , user.email , user.full_name , user.first_name , user.last_name , created_at , children , media_collection , media_collection.id , media_collection.name , tag_scheme , tag_scheme.id , tag_scheme.name , annotation_count , data , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
annotation_count() , usergroup_count()
Preprocessors:
get_single_auth_preprocessor(): Assert object view permission from shared usergroups. Checks current_user has view permission.
DELETE

/api/annotation_set/<int:id>

Delete single annotation_set object with id field matching param id

Preprocessors:
delete_auth_preprocessor(): None
POST

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

:param cascade: whether or not to share parent media collection :param instance_id: :param group_id: :return:

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/groups

Get all groups that contain this resource or collection of resources.

GET

/api/annotation_set/<int:instance_id>/groups

Get all groups that contain this resource or collection of resources.

GET

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

None
GET

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

None
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 api_query for instructions on making search queries. In addition it accepts include_columns and include_methods parameters which override returned fields of annotation model.

GET

/api/annotation_set/<int:instance_id>/labels/<list_type>

Returns lists of the labels used in the annotation_set with an ID matching id. The list_type parameter must one of recent or frequent which returns the most recently use or the most frequently used labels, respectively. The number of results returned can be controlled with the results_per_page query parameter.

MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
name VARCHAR(80) None False None False None
description TEXT None True None False None
media_collection_id INTEGER None False None False None
tag_scheme_id INTEGER None False None False None
user_id INTEGER None True None False None
created_at DATETIME function False None False None
parent_annotation_set_id INTEGER None True None False None
is_exemplar BOOLEAN False True None False None
type VARCHAR(80) base True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
usergroups groups List of groups objects that contain this resource
media_collection media_collection None
tag_scheme tag_scheme None
user users None
parent_annotation_set annotation_set None
media_annotations media_annotation List of media_annotation objects
annotations annotation List of related ${annotation} objects
children annotation_set None
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
current_user_can_edit Whether or not the current logged in user has edit permission (owner or edit_member)
current_user_is_member Whether or not the current logged in user is a member of a group that includes this object
current_user_can_view Whether or not the current user has permission to view this object
current_user_is_owner Whether or not the currently logged in user is the owner of this object
is_public Whether or not this object is public (i.e. shared in a public group)
current_user_is_edit_member Whether or not the current logged in user is a member with edit permission of a group that includes this object
ENDPOINTS
METHODENDPOINT
POST

/api/annotation_tags

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/annotation_tags

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

/api/annotation_tags/<int:id>

Get single annotation_tags object with id field matching param id
DELETE

/api/annotation_tags/<int:id>

Delete single annotation_tags object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
annotation_id INTEGER None False None True None
tag_id INTEGER None False None True None
assoc_created_at DATETIME function True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
annotation annotation None
tag tag None
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.

Preprocessors:
assert_user_login(): Restrict request to logged in users only
Postprocessors:
_clear_cache(): None
PATCH

/api/campaign/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
Postprocessors:
_clear_cache(): None
GET

/api/campaign

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

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

/api/campaign/<int:id>

Get single campaign object with id field matching param id

Included fields:
color , id , key , name , platform , platform.id , platform.name (see below for more details)
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/campaign/<int:id>

Delete single campaign object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
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
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False None
key VARCHAR(80) None False None False None
color VARCHAR(10) function True False False None
description TEXT None True None False None
user_id INTEGER None False None False None
created_at DATETIME function False None False None
platform_id INTEGER None False None False None
media_path_pattern TEXT None True None False None
thm_path_pattern TEXT None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
platform platform None
deployments deployment None
info campaigninfo None
files campaign_file None
ENDPOINTS
METHODENDPOINT
POST

/api/campaign_file

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/campaign_file

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

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

/api/campaign_file/<int:id>

Get single campaign_file object with id field matching param id

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

/api/campaign_file/<int:id>

Delete single campaign_file object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
GET

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

File Resource Get file with id= in specified format with optional file operations applied to file. :param URL: int: id: ID of file to get :param GET: json: queryparams: execute a file munge operations (see file munge documentation for more info) :param GET: string: format: one of [ 'image' | 'attachment' (default) | 'text' ] and denotes the mimetype/output format. :returns PATCH: mixed: file data in format and with appropriate mimetype defined by querystring param 'format'

POST

/api/campaign_file/save

File Resource Save file to database. Either upload 'file' OR point to a 'fileurl' (Note: either/or not both!) :param POST: string: fileurl: is a URL pointing to HTTP accessible file to download and save :param POST: Multipart/form-data: file: posted file data of uploaded file to save (multiple files will share description) :param POST: string: description: OPTIONAL Description of file. If omitted will be null :param POST: string: name: OPTIONAL title for file. If omitted file will be inferred from data. :param GET: json: queryparams: execute a file munge operations (see file munge documentation for more info) :param GET: string: format: one of [ 'image' | 'attachment' (default) | 'text' ] and denotes the mimetype/output format. :returns POST: json: response from POST operation including ID of newly created entry

MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(512) None False False False None
description TEXT None True None False None
rawfiledata BLOB None True None False None
iscompressed BOOLEAN False True None False None
user_id INTEGER None False None False None
campaign_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
campaign campaign None
HYBRID PROPERTIES
NAME DESCRIPTION
fileurl None
ENDPOINTS
METHODENDPOINT
POST

/api/campaigninfo

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/campaigninfo

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

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

/api/campaigninfo/<int:id>

Get single campaigninfo object with id field matching param id

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

/api/campaigninfo/<int:id>

Delete single campaigninfo object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False None
description TEXT None False None False None
created_at DATETIME function False None False None
campaign_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
campaign campaign None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/deployment

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

Included fields:
name , key , id , campaign_id , campaign , campaign.id , campaign.name (see below for more details)
Included methods:
color()
GET

/api/deployment/<int:id>

Get single deployment object with id field matching param id

Included fields:
name , key , id , campaign_id , campaign , campaign.id , campaign.name (see below for more details)
Included methods:
color()
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/deployment/<int:id>

Delete single deployment object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
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
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False None
key VARCHAR(80) None False None False None
campaign_id INTEGER None False None False None
user_id INTEGER None False None False None
created_at DATETIME function False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
campaign campaign None
user users None
poses pose None
media media None
events deployment_event None
HYBRID PROPERTIES
NAME DESCRIPTION
timestamp None
latlon None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/deployment_event/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/deployment_event

Get list of deployment_event objects matching API query. See api_query 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)
GET

/api/deployment_event/<int:id>

Get single deployment_event object with id 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)
DELETE

/api/deployment_event/<int:id>

Delete single deployment_event object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
description TEXT None False None False None
user_id INTEGER None False None False None
created_at DATETIME function False None False None
timestamp DATETIME function False None False None
pose_id INTEGER None True None False None
media_id INTEGER None True None False None
deployment_event_type_id INTEGER None False None False None
deployment_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
pose pose None
media media None
deployment_event_type deployment_event_type None
deployment deployment None
ENDPOINTS
METHODENDPOINT
POST

/api/deployment_event_type

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/deployment_event_type/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/deployment_event_type

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

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

/api/deployment_event_type/<int:id>

Get single deployment_event_type object with id field matching param id

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

/api/deployment_event_type/<int:id>

Delete single deployment_event_type object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
name VARCHAR(80) None False True False None
RELATED MODELS
FIELD RELATION DESCRIPTION
deployment_events deployment_event None
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
POST

/api/groups

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

Preprocessors:
group_type_preprocessor(): None
Postprocessors:
post_postprocessor(): None
PATCH

/api/groups/<int:id>

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

Preprocessors:
group_type_preprocessor(): None
assert_user_login(): Restrict request to logged in users only
GET

/api/groups

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

Included fields:
id , name , is_public , description , user , user.id , user.first_name , user.last_name , is_restricted , group_type , groupinfo , created_at , current_user_is_edit_member , current_user_is_member , current_user_is_owner , current_user_is_pending_approval (see below for more details)
Included methods:
member_count() , pending_member_count()
GET

/api/groups/<int:id>

Get single groups object with id field matching param id

Included fields:
id , name , is_public , description , user , user.id , user.first_name , user.last_name , is_restricted , group_type , groupinfo , created_at , current_user_is_edit_member , current_user_is_member , current_user_is_owner , current_user_is_pending_approval (see below for more details)
Included methods:
member_count() , pending_member_count()
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/groups/<int:id>

Delete single groups object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(128) None False None False None
is_public BOOLEAN False True None False None
is_restricted BOOLEAN True True None False None
description TEXT None True None False None
user_id INTEGER None True None False None
group_type_id INTEGER None False None False None
groupinfo TEXT None True None False None
created_at DATETIME function False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
group_type group_types None
members users None
usergroups usergroups None
added_tag_schemes tag_scheme None
added_media_collections media_collection None
added_annotation_sets annotation_set None
HYBRID PROPERTIES
NAME DESCRIPTION
current_user_is_member :return:
current_user_is_owner :return:
current_user_is_edit_member :return:
current_user_is_pending_approval :return:
ENDPOINTS
METHODENDPOINT
POST

/api/maplayer

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

Preprocessors:
assert_current_user_is_admin(): Restrict request to ADMIN user only
assert_user_login(): Restrict request to logged in users only
PATCH

/api/maplayer/<int:id>

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

Preprocessors:
assert_current_user_is_admin(): Restrict request to ADMIN user only
assert_user_login(): Restrict request to logged in users only
GET

/api/maplayer

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

/api/maplayer/<int:id>

Get single maplayer object with id field matching param id
DELETE

/api/maplayer/<int:id>

Delete single maplayer object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(255) None False None False None
baseurl VARCHAR(255) None False None False None
layertype VARCHAR(128) None False None False None
properties JSON None True None False None
ENDPOINTS
METHODENDPOINT
POST

/api/media

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
Postprocessors:
_clear_cache(): None
PATCH

/api/media/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
Postprocessors:
_clear_cache(): None
GET

/api/media

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

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

/api/media/<int:id>

Get single media object with id field matching param id

Included fields:
created_at , path_best , timestamp_start , is_valid , key , media_type_id , deployment_id , data , id , path_best_thm , media_type (see below for more details)
Postprocessors:
get_info_single_postprocessor(): None
DELETE

/api/media/<int:id>

Delete single media object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
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. :param URL: int: id: ID of something :param POST: file: file: filedata input containing image file to upload. :param POST: int: deployment_id: ID of deployment :param POST: string: media_type: type of media item (image|youtube|slippy_tiles) :param POST: string: path_thm: OPTIONAL. path to media thumbnail. If omitted, will use parent path pattern. :returns POST: json: a json string containing the newly created instance. :param GET: string: something_else: This is something else... :param GET: string: file: file post field containing media data to save :returns GET: json: a json string containing the structure of stuff

GET

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

Dynamically create thumbnail. If user is logged in, then they can request different sizes

MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
key VARCHAR(80) None False None False None
path TEXT None True None False None
path_thm TEXT None True None False None
is_valid BOOLEAN True True None False None
deployment_id INTEGER None False None False None
media_type_id INTEGER None False None False None
timestamp_start DATETIME function True None False None
created_at DATETIME function True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
deployment deployment None
media_type media_type None
annotations media_annotation List of media_annotation objects
media_collection_media media_collection_media None
mediaposes media_poses None
events deployment_event None
HYBRID PROPERTIES
NAME DESCRIPTION
path_best None
path_best_thm None
data JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
PATCH

/api/media_annotation/<int:id>

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

Preprocessors:
edit_auth_preprocessor(): None
assert_user_login(): Restrict request to logged in users only
GET

/api/media_annotation

Get list of media_annotation objects matching API query. See api_query for instructions on making search queries

Included fields:
media_id , annotation_set_id , t , x , y , suggested_labels , data , id , annotation_labels , annotation_labels.id , annotation_labels.annotation_set_id (see below for more details)
GET

/api/media_annotation/<int:id>

Get single media_annotation object with id field matching param id

Included fields:
media_id , annotation_set_id , t , x , y , suggested_labels , data , id , annotation_labels , annotation_labels.id , annotation_labels.annotation_set_id (see below for more details)
Preprocessors:
view_auth_preprocessor(): None
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/media_annotation/<int:id>

Delete single media_annotation object with id field matching param id

Preprocessors:
edit_auth_preprocessor(): None
assert_user_is_owner(): Restrict request to object OWNER only
POST

/api/media_annotation

Custom post endpoint
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
x FLOAT None True False False X location of point as a proportion across the frame width (0-1.0) or latitude for map objects
y FLOAT None True False False Y location of point as a proportion across the frame height (0-1.0) or longitude for map objects
t FLOAT None True False False Number of seconds of annotation relative to media.start_time (eg: for video)
media_id INTEGER None False None False Foreign key id of media object linked to media_annotation
annotation_set_id INTEGER None False None False Foreign key id of the parent/origin annotation_set. I.e.: the one linked to the initial creation of the media_annotation
RELATED MODELS
FIELD RELATION DESCRIPTION
media media Related media object
annotation_set annotation_set Parent/origin annotation_set object
annotation_labels annotation List of annotation objects
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/media_collection/<int:id>

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

Preprocessors:
patch_auth_preprocessor(): Assert object edit permission from shared usergroups. Checks current_user has edit permission.
assert_user_login(): Restrict request to logged in users only
GET

/api/media_collection

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

Included fields:
id , name , parent_collection_id , description , user , created_at , children , user.id , user.email , user.full_name , user.first_name , user.last_name , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
usergroup_count()
Preprocessors:
get_many_auth_preprocessor(): Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view
GET

/api/media_collection/<int:id>

Get single media_collection object with id field matching param id

Included fields:
id , name , parent_collection_id , description , user , created_at , children , user.id , user.email , user.full_name , user.first_name , user.last_name , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
usergroup_count()
Preprocessors:
get_single_auth_preprocessor(): Assert object view permission from shared usergroups. Checks current_user has view permission.
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/media_collection/<int:id>

Delete single media_collection object with id field matching param id

Preprocessors:
delete_auth_preprocessor(): Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup
assert_user_is_owner(): Restrict request to object OWNER only
POST

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

:param cascade: whether or not to share child annotation sets :param instance_id: :param group_id: :return:

DELETE

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

None
GET

/api/media_collection/groups

Get all groups that contain this resource or collection of resources.

GET

/api/media_collection/<int:instance_id>/groups

Get all groups that contain this resource or collection of resources.

GET

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

None
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 api_query 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 api_query 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
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
data_json TEXT None True None False Text field containing JSON properties for this resource
name VARCHAR(80) None False None False The name of the media_collection
description TEXT None True None False A concise description of the media_collection
parent_collection_id INTEGER None True None False A reference to the ID of a parent media_collection
created_at DATETIME function False None False The creation date-time
user_id INTEGER None True None False Foreign key reference for ID of related owner users model
RELATED MODELS
FIELD RELATION DESCRIPTION
user users Related owner users model
usergroups groups List of groups objects that contain this resource
parent media_collection The parent media_collection instance
media media A list of media contained in this media_collection
annotation_sets annotation_set None
children media_collection A list of childen media_collections that belong to this one
media_collection_media media_collection_media None
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
current_user_can_edit Whether or not the current logged in user has edit permission (owner or edit_member)
current_user_is_member Whether or not the current logged in user is a member of a group that includes this object
current_user_can_view Whether or not the current user has permission to view this object
current_user_is_owner Whether or not the currently logged in user is the owner of this object
is_public Whether or not this object is public (i.e. shared in a public group)
current_user_is_edit_member Whether or not the current logged in user is a member with edit permission of a group that includes this object
ENDPOINTS
METHODENDPOINT
POST

/api/media_collection_media

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/media_collection_media

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

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

/api/media_collection_media/<int:id>

Get single media_collection_media object with id field matching param id

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

/api/media_collection_media/<int:id>

Delete single media_collection_media object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
media_id INTEGER None False None True None
media_collection_id INTEGER None False None True None
created_at DATETIME function False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
media media None
media_collection media_collection None
ENDPOINTS
METHODENDPOINT
POST

/api/media_poses

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/media_poses

Get list of media_poses objects matching API query. See api_query for instructions on making search queries
GET

/api/media_poses/<int:id>

Get single media_poses object with id field matching param id
DELETE

/api/media_poses/<int:id>

Delete single media_poses object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
media_id INTEGER None False None True None
pose_id INTEGER None False None True None
RELATED MODELS
FIELD RELATION DESCRIPTION
media media None
pose pose None
ENDPOINTS
METHODENDPOINT
POST

/api/media_type

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/media_type

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

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

/api/media_type/<int:id>

Get single media_type object with id field matching param id

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

/api/media_type/<int:id>

Delete single media_type object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False The name of the media type
RELATED MODELS
FIELD RELATION DESCRIPTION
media media None
ENDPOINTS
METHODENDPOINT
POST

/api/platform

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/platform/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/platform

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

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

/api/platform/<int:id>

Get single platform object with id field matching param id

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

/api/platform/<int:id>

Delete single platform object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
PUT

/api/platform_file/<int:fid>

None
GET

/api/platform_file/<int:fid>

None
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
rawfiledata BLOB None True None False None
iscompressed BOOLEAN False True None False None
data_json TEXT None True None False Text field containing JSON properties for this resource
name VARCHAR(80) None False True False None
description TEXT None True None False None
reference TEXT None True None False None
user_id INTEGER None True None False None
created_at DATETIME function False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
layers platform_maplayer None
campaigns campaign None
HYBRID PROPERTIES
NAME DESCRIPTION
data JSON data containing optional properties for this resource
ENDPOINTS
METHODENDPOINT
POST

/api/platform_maplayer

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

Preprocessors:
assert_current_user_is_admin(): Restrict request to ADMIN user only
assert_user_login(): Restrict request to logged in users only
PATCH

/api/platform_maplayer/<int:id>

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

Preprocessors:
assert_current_user_is_admin(): Restrict request to ADMIN user only
assert_user_login(): Restrict request to logged in users only
GET

/api/platform_maplayer

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

/api/platform_maplayer/<int:id>

Get single platform_maplayer object with id field matching param id
DELETE

/api/platform_maplayer/<int:id>

Delete single platform_maplayer object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(255) None False None False None
baseurl VARCHAR(255) None False None False None
layertype VARCHAR(128) None False None False None
minzoom INTEGER None True None False None
properties JSON None True None False None
platform_id INTEGER None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
platform platform None
ENDPOINTS
METHODENDPOINT
POST

/api/pose

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/pose

Get list of pose objects matching API query. See api_query 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 (see below for more details)
GET

/api/pose/<int:id>

Get single pose object with id 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 (see below for more details)
DELETE

/api/pose/<int:id>

Delete single pose object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
lat FLOAT None True False False None
lon FLOAT None True False False None
alt FLOAT None True False False None
dep FLOAT None True False False None
timestamp DATETIME function False None False None
deployment_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
deployment deployment None
data posedata None
mediaposes media_poses None
events deployment_event None
ENDPOINTS
METHODENDPOINT
POST

/api/posedata

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/posedata

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

/api/posedata/<int:id>

Get single posedata object with id field matching param id
DELETE

/api/posedata/<int:id>

Delete single posedata object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False None
value FLOAT None True False False None
pose_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
pose pose None
ENDPOINTS
METHODENDPOINT
POST

/api/roles

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/roles/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/roles

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

/api/roles/<int:id>

Get single roles object with id field matching param id
DELETE

/api/roles/<int:id>

Delete single roles object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False True False None
ENDPOINTS
METHODENDPOINT
POST

/api/tag

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

Preprocessors:
post_preprocessor(): None
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag

Get list of tag objects matching API query. See api_query 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)
GET

/api/tag/<int:id>

Get single tag object with id 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)
DELETE

/api/tag/<int:id>

Delete single tag object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False None False None
user_id INTEGER None False None False None
type_id INTEGER None True None False None
synonym_tag_id INTEGER None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
type tag_type None
synonym_tag tag None
synonyms tag None
taggrouptags tag_group_tags None
annotationtags annotation_tags None
HYBRID PROPERTIES
NAME DESCRIPTION
is_synonym None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_group

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

Preprocessors:
edit_auth_preprocessor(): checks that the current user has permission to edit this class label.
validate_preprocessor(): 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 (tag_scheme_id) and is not a circular reference to itself (witch can break things).
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_group/<int:id>

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

Preprocessors:
edit_auth_preprocessor(): checks that the current user has permission to edit this class label.
validate_preprocessor(): 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 (tag_scheme_id) and is not a circular reference to itself (witch can break things).
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_group

Get list of tag_group objects matching API query. See api_query for instructions on making search queries

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

/api/tag_group/<int:id>

Get single tag_group object with id field matching param id

Included fields:
user_id , name , color , parent_id , tag_scheme_id , id , uuid , is_child , is_parent , created_at , updated_at , is_approved (see below for more details)
Postprocessors:
get_single_postprocessor(): adds additional computed fields to single request including: info, tags, tag_scheme, parent, lineage_names, current_user_can_edit, annotation_count, descendant_count, user, current_user_is_custodian
DELETE

/api/tag_group/<int:id>

Delete single tag_group object with id field matching param id

Preprocessors:
edit_auth_preprocessor(): checks that the current user has permission to edit this class label.
delete_preprocessor(): checks that the class label does not have any children or annotations which may be orphaned by delete.
DELETE

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

None
POST

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

None
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
uuid UUID None True True False A universally unique identifier for this object
name VARCHAR(160) None False False False The name of this class label
color VARCHAR(10) function True False False The colour of this class label (hex code, including #)
user_id INTEGER None False None False The id of the user who owns or created this class label
tag_scheme_id INTEGER None False None False The id of the annotation scheme (tag_scheme) containing this class label
parent_id INTEGER None True None False id of the parent class label
is_approved BOOLEAN False True None False Whether this class label has been approved by the custodian
created_at DATETIME function True None False Creation time (UTC)
updated_at TIMESTAMP function True None False Updated time (UTC)
RELATED MODELS
FIELD RELATION DESCRIPTION
user users The user who owns or created this class label
tag_scheme tag_scheme The annotation scheme containing this class label
parent tag_group The parent class label
children tag_group None
taggrouptags tag_group_tags None
info tag_group_info None
annotations annotation List of related annotation objects
HYBRID PROPERTIES
NAME DESCRIPTION
is_parent BOOLEAN, whether or not this class label has children / descendants
is_child BOOLEAN, whether or not this class label has a parent class label
ENDPOINTS
METHODENDPOINT
POST

/api/tag_group_info

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_group_info/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_group_info

Get list of tag_group_info objects matching API query. See api_query for instructions on making search queries
GET

/api/tag_group_info/<int:id>

Get single tag_group_info object with id field matching param id
DELETE

/api/tag_group_info/<int:id>

Delete single tag_group_info object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False False False None
value TEXT None True None False None
tag_group_id INTEGER None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
tag_group tag_group None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_group_tags

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_group_tags/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_group_tags

Get list of tag_group_tags objects matching API query. See api_query for instructions on making search queries
GET

/api/tag_group_tags/<int:id>

Get single tag_group_tags object with id field matching param id
DELETE

/api/tag_group_tags/<int:id>

Delete single tag_group_tags object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
tag_group_id INTEGER None False None True None
tag_id INTEGER None False None True None
assoc_created_at DATETIME function True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
tag_group tag_group None
tag tag None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_scheme

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_scheme/<int:id>

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

Preprocessors:
patch_auth_preprocessor(): Assert object edit permission from shared usergroups. Checks current_user has edit permission.
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_scheme

Get list of tag_scheme objects matching API query. See api_query for instructions on making search queries

Included fields:
user_id , description , is_hierarchy , id , name , user , user.username , user.first_name , user.last_name , user.id , tag_files , tag_files.description , tag_files.fileurl , tag_files.id , tag_files.name , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
usergroup_count() , annotation_set_count()
Preprocessors:
get_many_auth_preprocessor(): Assert object view permission from shared usergroups. Restricts objects to the ones that current_user can view
GET

/api/tag_scheme/<int:id>

Get single tag_scheme object with id field matching param id

Included fields:
user_id , description , is_hierarchy , id , name , user , user.username , user.first_name , user.last_name , user.id , tag_files , tag_files.description , tag_files.fileurl , tag_files.id , tag_files.name , current_user_can_view , current_user_is_owner , current_user_is_member , current_user_can_edit , is_public (see below for more details)
Included methods:
usergroup_count() , annotation_set_count()
Preprocessors:
get_single_auth_preprocessor(): Assert object view permission from shared usergroups. Checks current_user has view permission.
Postprocessors:
get_single_postprocessor(): adds additional computed fields to single request including: info, tags, tag_scheme, parent, lineage_names, current_user_can_edit, annotation_count, descendant_count, user, current_user_is_custodian
DELETE

/api/tag_scheme/<int:id>

Delete single tag_scheme object with id field matching param id

Preprocessors:
delete_auth_preprocessor(): Assert object delete permission from shared usergroups. Checks current user is owner and object is not shared in a usergroup
assert_user_is_owner(): Restrict request to object OWNER only
POST

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

Add object with id instance_id to group with id group_id
DELETE

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

Remove resource with id instance_id from group with id group_id
GET

/api/tag_scheme/groups

Get all groups that contain this resource or collection of resources.

GET

/api/tag_scheme/<int:instance_id>/groups

Get all groups that contain this resource or collection of resources.

GET

/api/tag_scheme/<int:id>/nested

None
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False False False None
description TEXT None True None False None
user_id INTEGER None False None False None
is_hierarchy BOOLEAN False True None False None
created_at DATETIME function True None False Creation time (UTC)
updated_at TIMESTAMP function True None False Updated time (UTC)
RELATED MODELS
FIELD RELATION DESCRIPTION
usergroups groups List of groups objects that contain this resource
user users None
exemplar_annotation_sets annotation_set None
tag_files tag_scheme_file None
tag_groups tag_group None
annotation_sets annotation_set None
HYBRID PROPERTIES
NAME DESCRIPTION
current_user_can_edit Whether or not the current logged in user has edit permission (owner or edit_member)
current_user_is_member Whether or not the current logged in user is a member of a group that includes this object
current_user_can_view Whether or not the current user has permission to view this object
current_user_is_owner Whether or not the currently logged in user is the owner of this object
is_public Whether or not this object is public (i.e. shared in a public group)
current_user_is_edit_member Whether or not the current logged in user is a member with edit permission of a group that includes this object
ENDPOINTS
METHODENDPOINT
PATCH

/api/tag_scheme_file/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_scheme_file

Get list of tag_scheme_file objects matching API query. See api_query for instructions on making search queries

Included fields:
description , iscompressed , tag_scheme , fileurl , tag_scheme_id , id , name (see below for more details)
GET

/api/tag_scheme_file/<int:id>

Get single tag_scheme_file object with id field matching param id

Included fields:
description , iscompressed , tag_scheme , fileurl , tag_scheme_id , id , name (see below for more details)
DELETE

/api/tag_scheme_file/<int:id>

Delete single tag_scheme_file object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
GET

/api/tag_scheme_file/get/<int:fid>

File Resource Get file with id= in specified format with optional file operations applied to file. :param URL: int: id: ID of file to get :param GET: json: queryparams: execute a file munge operations (see file munge documentation for more info) :param GET: string: format: one of [ 'image' | 'attachment' (default) | 'text' ] and denotes the mimetype/output format. :returns PATCH: mixed: file data in format and with appropriate mimetype defined by querystring param 'format'

POST

/api/tag_scheme_file/save

File Resource Save file to database. Either upload 'file' OR point to a 'fileurl' (Note: either/or not both!) :param POST: string: fileurl: is a URL pointing to HTTP accessible file to download and save :param POST: Multipart/form-data: file: posted file data of uploaded file to save (multiple files will share description) :param POST: string: description: OPTIONAL Description of file. If omitted will be null :param POST: string: name: OPTIONAL title for file. If omitted file will be inferred from data. :param GET: json: queryparams: execute a file munge operations (see file munge documentation for more info) :param GET: string: format: one of [ 'image' | 'attachment' (default) | 'text' ] and denotes the mimetype/output format. :returns POST: json: response from POST operation including ID of newly created entry

MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(512) None False False False None
description TEXT None True None False None
rawfiledata BLOB None True None False None
iscompressed BOOLEAN False True None False None
tag_scheme_id INTEGER None False None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
tag_scheme tag_scheme None
HYBRID PROPERTIES
NAME DESCRIPTION
fileurl None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_synonym

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_synonym/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_synonym

Get list of tag_synonym objects matching API query. See api_query for instructions on making search queries
GET

/api/tag_synonym/<int:id>

Get single tag_synonym object with id field matching param id
DELETE

/api/tag_synonym/<int:id>

Delete single tag_synonym object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
RELATED MODELS
FIELD RELATION DESCRIPTION
synonym_tags tag None
ENDPOINTS
METHODENDPOINT
POST

/api/tag_type

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
PATCH

/api/tag_type/<int:id>

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

Preprocessors:
assert_user_login(): Restrict request to logged in users only
GET

/api/tag_type

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

/api/tag_type/<int:id>

Get single tag_type object with id field matching param id
DELETE

/api/tag_type/<int:id>

Delete single tag_type object with id field matching param id

Preprocessors:
assert_user_is_owner(): Restrict request to object OWNER only
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
name VARCHAR(80) None False True False None
description TEXT None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
tags tag None
ENDPOINTS
METHODENDPOINT
GET

/api/usergroups

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

/api/usergroups/<int:id>

Get single usergroups object with id field matching param id
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
user_id INTEGER None False None True None
group_id INTEGER None False None True None
created_at DATETIME function True None False None
approved BOOLEAN False True None False None
can_edit BOOLEAN False True None False None
added_by_user_id INTEGER None True None False None
RELATED MODELS
FIELD RELATION DESCRIPTION
user users None
group groups None
ENDPOINTS
METHODENDPOINT
GET

/api/users

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

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

/api/users/<int:id>

Get single users object with id field matching param id

Included fields:
id , user_created_at , last_login , first_name , last_name , active , info , role , affiliations , affiliations.name , affiliations.groupinfo , affiliations.id (see below for more details)
Postprocessors:
get_single_postprocessor(): None
DELETE

/api/users/<int:id>

Delete single users object with id field matching param id

Preprocessors:
assert_current_user_is_admin(): Restrict request to ADMIN user only
assert_user_is_owner(): Restrict request to object OWNER only
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

Manage user session login
DELETE

/api/users/login

Manage user session login
POST

/api/users

Create new user account
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
MODEL COLUMNS
NAME TYPE DEFAULT NULLABLE UNIQUE PRIMARY_KEY DESCRIPTION
id INTEGER None False None True Primary key id
username VARCHAR(80) None False True False None
email VARCHAR(80) None False True False None
password VARCHAR(128) None False None False None
created_at DATETIME function False None False None
last_login DATETIME now() True None False None
first_name VARCHAR(30) None False None False None
last_name VARCHAR(30) None False None False None
active BOOLEAN True True None False None
is_admin BOOLEAN False True None False None
info TEXT None True None False None
role_id INTEGER None True None False None
api_token VARCHAR(80) None True True False None
RELATED MODELS
FIELD RELATION DESCRIPTION
role roles None
affiliations_usergroups usergroups None
usergroups usergroups None

Making API search queries

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

Pagination

Responses to GET requests 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:

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, <fieldname> is the name of the field of the model to which to apply the operator, <argument> is a value to be used as the second argument to the given operator.

{"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
  • 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 and use the has operator if the relation is a single object.

Filters can also exclude results, for example:

{"not": <filterobject>}

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

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

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>.

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.

API Example queries

Get all media_collections that contain media from a specific campaign matching the key "Batemans201011": 

/api/media_collection?q={"filters":[{"name":"media","op":"any","val":{"name":"deployment","op":"has","val":{"name":"campaign","op":"has","val":{"name":"key","op":"eq","val":"Batemans201011"}}}}]}

Get all annotation_sets that contain media from deployment with a name starting with "site5" (ignoring case): 

/api/annotation_set?q={"filters":[{"name":"media_collection","op":"has","val":{"name":"media","op":"any","val":{"name":"deployment","op":"has","val":{"name":"name","op":"ilike","val":"site5%"}}}}]}

Search for all media that contains annotations with the name that includes "ecklonia" (ignoring case) 

/api/media?q={"filters":[{"name":"annotations","op":"any","val":{"name":"annotation_labels","op":"any","val":{"name":"tag_group","op":"has","val":{"name":"name","op":"ilike","val":"%ecklonia%"}}}}]}

Search for all media that contains annotations with a tag that includes the word "review" (ignoring case) 

/api/media?q={"filters":[{"name":"annotations","op":"any","val":{"name":"annotation_labels","op":"any","val":{"name":"tags","op":"any","val":{"name":"name","op":"ilike","val":"%review%"}}}}]}

Search for annotations in an annotation_set matching id=84 that have the tag_group_id=310 

/api/annotation_set/84/annotations?include_columns=["tag_group_id","id","color","media_annotation","media_annotation.media_id","media_annotation.id"]&q={"filters":[{"name":"tag_group_id","op":"eq","val":310}]}&results_per_page=100

Code snippets

Create an empty media_collection 

# Setup initial params
api_token = "..."               # Set this to your API token for your account
url = "https://squidle.org"     # Be sure to set this to the correct instance that you're working on

# get user_id
params={"q": json.dumps({"filters":[{"name":"api_token","op":"eq","val":api_token}],"single":True})}
user_id = requests.get(url+"/api/users", params=params).json().get("id")

# parameters for new media_collection
payload = {
    "name": "API test 01",
    "description":"Testing API-created media_collection",
    "user_id": user_id
}
headers={
    "auth-token": api_token,
    "Content-type": "application/json",
    "Accept": "application/json",
}

# Make resquest
r = requests.post(
    url+"/api/media_collection",
    headers=headers,
    json=payload,
)

# Check results
new_media_collection = r.json()
media_collection_id = new_media_collection.get("id")