Skip to main content
Documentation Powered by Redocly

Tator REST API (1.2.4)

Download OpenAPI specification:Download

Tator

GetAnonymousGatewaySchema

Allows for logging into Tator as an anonymous user.

Authorizations:
TokenAuthSessionAuth
query Parameters
redirect
string

URI to redirect to after logging in as anonymous user. Defaults to /projects.

Responses

Response samples

Content type
[
  • null
]

DeleteAffiliation

Delete affiliation.

Affiliations specify a permission level of a user to an organization. There are currently two cumulative permission levels. Member can only view an organization and not change any data. Admin can modify an organization, add members to an organization, and create new projects under the organization's account.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a affiliation.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAffiliation

Get affiliation.

Affiliations specify a permission level of a user to an organization. There are currently two cumulative permission levels. Member can only view an organization and not change any data. Admin can modify an organization, add members to an organization, and create new projects under the organization's account.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a affiliation.

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "first_name": "string",
  • "id": 0,
  • "last_name": "string",
  • "organization_id": 1,
  • "permission": "Member",
  • "user_id": 1,
  • "username": "string"
}

UpdateAffiliation

Update affiliation.

Affiliations specify a permission level of a user to an organization. There are currently two cumulative permission levels. Member can only view an organization and not change any data. Admin can modify an organization, add members to an organization, and create new projects under the organization's account.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a affiliation.

Request Body schema: application/json
permission
string
Enum: "Member" "Admin"

User permission level for the organization.

Responses

Request samples

Content type
application/json
{
  • "permission": "View Only"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAffiliationList

Get affiliation list.

Affiliations specify a permission level of a user to an organization. There are currently two cumulative permission levels. Member can only view an organization and not change any data. Admin can modify an organization, add members to an organization, and create new projects under the organization's account.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateAffiliation

Create affiliation.

Affiliations specify a permission level of a user to an organization. There are currently two cumulative permission levels. Member can only view an organization and not change any data. Admin can modify an organization, add members to an organization, and create new projects under the organization's account.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Request Body schema: application/json
permission
string
Enum: "Member" "Admin"

User permission level for the organization.

user
integer >= 1

Unique integer identifying a user.

Responses

Request samples

Content type
application/json
{
  • "permission": "Admin",
  • "user": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteAlgorithm

Delete registered algorithm workflow

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered algorithm workflow.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAlgorithm

Get registered algorithm workflow

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered algorithm workflow.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "cluster": 0,
  • "description": "string",
  • "files_per_job": 0,
  • "id": 0,
  • "manifest": "string",
  • "name": "string",
  • "parameters": [
    ],
  • "project": 0,
  • "user": 0
}

UpdateAlgorithm

Updated registered algorithm workflow

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered algorithm workflow.

Request Body schema: application/json
categories
Array of strings

List of categories the algorithm workflow belongs to

cluster
integer or null

Unique integer identifying the job cluster.

description
string

Description of the algorithm.

files_per_job
required
integer

Number of media files to be submitted to each workflow.

manifest
required
string

Server URL to argo manifest file (.yaml)

name
required
string

Unique name of the algorithm workflow.

Array of objects (AlgorithmParameter)

List of algorithm workflow parameters

user
required
integer

Unique integer identifying the user registering the algorithm.

Responses

Request samples

Content type
application/json
{
  • "manifest": "Server path to new manifest file",
  • "name": "New unique name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAlgorithmList

Get registered algorithms.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

RegisterAlgorithm

Register an algorithm argo workflow.

This endpoint replicates the algorithm registration through the admin portal. The provided manifest file must have been uploaded and saved by the SaveAlgorithmManifest endpoint. This endpoint will respond with an error if one of the following conditions occur:

  • Provided workflow name is not unique (across projects)
  • Not all the required fields are present
  • There are syntax errors with the given manifest file
Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
categories
Array of strings

List of categories the algorithm workflow belongs to

cluster
integer or null

Unique integer identifying the job cluster.

description
string

Description of the algorithm.

files_per_job
required
integer

Number of media files to be submitted to each workflow.

manifest
required
string

Server URL to argo manifest file (.yaml)

name
required
string

Unique name of the algorithm workflow.

Array of objects (AlgorithmParameter)

List of algorithm workflow parameters

user
required
integer

Unique integer identifying the user registering the algorithm.

Responses

Request samples

Content type
application/json
{
  • "categories": [
    ],
  • "cluster": 0,
  • "description": "string",
  • "files_per_job": 0,
  • "manifest": "string",
  • "name": "string",
  • "parameters": [
    ],
  • "user": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteAnnouncement

Delete announcement.

Announcements are system-wide messages sent to users. Users may delete individual announcements to acknowledge and stop displaying them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a announcement.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAnnouncementList

Get announcement list.

Announcements are system-wide messages sent to users. Users may delete individual announcements to acknowledge and stop displaying them.

Authorizations:
TokenAuthSessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

DeleteApplet

Delete registered applet file

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered applet file.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetApplet

Get registered applet file

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered applet file.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "description": "string",
  • "html_file": "string",
  • "id": 0,
  • "name": "string",
  • "project": 0
}

UpdateApplet

Updated registered applet file

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered applet file.

Request Body schema: application/json
categories
Array of strings

List of categories the applet belongs to

description
string

Description of applet

html_file
string

Server URL to applet HTML file

name
string

Name of applet

Responses

Request samples

Content type
application/json
{
  • "name": "New applet name"
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

GetAppletList

Get applet list.

Applets are customized interfaces (i.e. html files) displayed within the Tator projects.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

RegisterApplet

Create applet.

Applets are customized interfaces (i.e. html files) displayed within the Tator projects.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
categories
Array of strings

List of categories the applet belongs to

description
string

Description of applet

html_file
string

Server URL to applet HTML file

name
string

Name of applet

Responses

Request samples

Content type
application/json
{
  • "categories": [
    ],
  • "description": "string",
  • "html_file": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteAttributeType

Deletes an existing attribute on Type.

A attribute type is the metadata definition object for a user-defined attribute. It includes name, type, and any other associated fields, depending on the type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a unique entity type.

Request Body schema: application/json
entity_type
string

The entity type containing the attribute to rename.

name
string

The attribute to delete.

Responses

Request samples

Content type
application/json
{
  • "entity_type": "LocalizationType",
  • "name": "My Old Attribute"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

UpdateAttributeType

Renames and/or changes the type of an existing attribute on Type.

A attribute type is the metadata definition object for a user-defined attribute. It includes name, type, and any other associated fields, depending on the type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a unique entity type.

Request Body schema: application/json
required
object
current_name
required
string

The attribute to rename.

entity_type
required
string

The entity type containing the attribute to rename.

Responses

Request samples

Content type
application/json
{
  • "attribute_type_update": {
    },
  • "current_name": "My Old Attribute",
  • "entity_type": "LocalizationType"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CreateAttributeType

Adds an attribute to Type.

A attribute type is the metadata definition object for a user-defined attribute. It includes name, type, and any other associated fields, depending on the type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a unique entity type.

Request Body schema: application/json
object (AttributeType)

The full definition of an attribute on an entity type.

entity_type
string

The entity type containing the attribute to rename.

Responses

Request samples

Content type
application/json
{
  • "addition": {
    },
  • "entity_type": "LocalizationType"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

ReplaceAttributeType

Replaces the definition of an existing attribute on Type.

WARNING This completely replaces the existing definition and will delete any existing fields that are not present in the attribute_type_update definition.

A attribute type is the metadata definition object for a user-defined attribute. It includes name, type, and any other associated fields, depending on the type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a unique entity type.

Request Body schema: application/json
required
object
current_name
required
string

The attribute to rename.

entity_type
required
string

The entity type containing the attribute to rename.

Responses

Request samples

Content type
application/json
{
  • "attribute_type_update": {
    },
  • "current_name": "My Old Attribute",
  • "entity_type": "LocalizationType"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteAudioFile

Delete audio file.

Audio files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying audio. One or more audio files can be used to reference the audio role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the audio file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "audio"
Value: "audio"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of audio files for the specified role.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAudioFile

Get audio file.

Audio files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying audio. One or more audio files can be used to reference the audio role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the audio file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "audio"
Value: "audio"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of audio files for the specified role.

Responses

Response samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "size": 0
}

UpdateAudioFile

Update audio file.

Audio files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying audio. One or more audio files can be used to reference the audio role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the audio file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "audio"
Value: "audio"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of audio files for the specified role.

Request Body schema: application/json
bit_rate
integer

Bit rate in bits per second

codec
required
string

Human readable codec.

codec_description
string

Description other than codec.

codec_mime
string

Example mime: "video/mp4; codecs="avc1.64001e"". Only relevant for streaming files, will assume example above if not present.

host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

path
required
string

Relative URL to the file.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAudioFileList

Get audio file list.

Audio files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying audio. One or more audio files can be used to reference the audio role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the audio file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "audio"
Value: "audio"

Role of media file being referenced.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateAudioFile

Create audio file.

Audio files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying audio. One or more audio files can be used to reference the audio role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the audio file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "audio"
Value: "audio"

Role of media file being referenced.

index
integer >= 0

Insertion index. Must be less than size of current list of audio files for the specified role. If omitted, the audio file will be appended to the end of the list.

Request Body schema: application/json
bit_rate
integer

Bit rate in bits per second

codec
required
string

Human readable codec.

codec_description
string

Description other than codec.

codec_mime
string

Example mime: "video/mp4; codecs="avc1.64001e"". Only relevant for streaming files, will assume example above if not present.

host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

path
required
string

Relative URL to the file.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteAuxiliaryFile

Delete auxiliary file.

Auxiliary files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying generic file. One or more files can be used to reference the attachment role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "attachment"
Value: "attachment"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of files for the specified role.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAuxiliaryFile

Get auxiliary file.

Auxiliary files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying generic file. One or more files can be used to reference the attachment role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "attachment"
Value: "attachment"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of files for the specified role.

Responses

Response samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "name": "string",
  • "path": "string",
  • "size": 0
}

UpdateAuxiliaryFile

Update auxiliary file.

Auxiliary files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying generic file. One or more files can be used to reference the attachment role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "attachment"
Value: "attachment"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of files for the specified role.

Request Body schema: application/json
host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

mime
string

Example mime: "text/csv".

name
string

Name of the file.

path
required
string

Relative URL to the file.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "name": "string",
  • "path": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetAuxiliaryFileList

Get file list.

Auxiliary files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying generic file. One or more files can be used to reference the attachment role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "attachment"
Value: "attachment"

Role of media file being referenced.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateAuxiliaryFile

Create file.

Auxiliary files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying generic file. One or more files can be used to reference the attachment role in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
string
Default: "attachment"
Value: "attachment"

Role of media file being referenced.

index
integer >= 0

Insertion index. Must be less than size of current list of files for the specified role. If omitted, the file will be appended to the end of the list.

Request Body schema: application/json
host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

mime
string

Example mime: "text/csv".

name
string

Name of the file.

path
required
string

Relative URL to the file.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "name": "string",
  • "path": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteBookmark

Delete bookmark.

Bookmarks are saved links that can be used to mark videos/frames of interest. They are scoped to a project and user, so if a user requests Bookmarks for a project they will only receive the Bookmarks created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bookmark.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetBookmark

Get bookmark.

Bookmarks are saved links that can be used to mark videos/frames of interest. They are scoped to a project and user, so if a user requests Bookmarks for a project they will only receive the Bookmarks created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bookmark.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "uri": "string",
  • "user": 1
}

UpdateBookmark

Update bookmark.

Bookmarks are saved links that can be used to mark videos/frames of interest. They are scoped to a project and user, so if a user requests Bookmarks for a project they will only receive the Bookmarks created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bookmark.

Request Body schema: application/json
name
string

Name of the bookmark.

uri
string

URI to the saved link.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "uri": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetBookmarkList

Get bookmark list.

Bookmarks are saved links that can be used to mark videos/frames of interest. They are scoped to a project and user, so if a user requests Bookmarks for a project they will only receive the Bookmarks created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
name
string

Name of the bookmark to filter on.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateBookmark

Create bookmark.

Bookmarks are saved links that can be used to mark videos/frames of interest. They are scoped to a project and user, so if a user requests Bookmarks for a project they will only receive the Bookmarks created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
name
string

Name of the bookmark to filter on.

Request Body schema: application/json
name
string

Name of the bookmark.

uri
string

URI to the saved link.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "uri": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteBucket

Delete bucket.

Buckets allow users to specify a project-specific S3 bucket to store media. Buckets are defined at the Organization level. Creating and setting a bucket on a project requires administrative access within the organization. Once a bucket is defined for a project, all media subsequently uploaded to that project will be stored in the bucket. Projects may have media in multiple buckets. For example, if a project is initially created without setting a separate bucket and media is uploaded, then the bucket field is updated and more media is uploaded, that project would then contain some media in the default bucket and some in the newly defined bucket.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bucket.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetBucket

Get bucket.

Buckets allow users to specify a project-specific S3 bucket to store media. Buckets are defined at the Organization level. Creating and setting a bucket on a project requires administrative access within the organization. Once a bucket is defined for a project, all media subsequently uploaded to that project will be stored in the bucket. Projects may have media in multiple buckets. For example, if a project is initially created without setting a separate bucket and media is uploaded, then the bucket field is updated and more media is uploaded, that project would then contain some media in the default bucket and some in the newly defined bucket.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bucket.

Responses

Response samples

Content type
application/json
{
  • "archive_sc": "STANDARD",
  • "endpoint_url": "string",
  • "external_host": "string",
  • "id": 0,
  • "live_sc": "STANDARD",
  • "name": "string",
  • "organization": 0,
  • "store_type": "AWS"
}

UpdateBucket

Update bucket.

Buckets allow users to specify a project-specific S3 bucket to store media. Buckets are defined at the Organization level. Creating and setting a bucket on a project requires administrative access within the organization. Once a bucket is defined for a project, all media subsequently uploaded to that project will be stored in the bucket. Projects may have media in multiple buckets. For example, if a project is initially created without setting a separate bucket and media is uploaded, then the bucket field is updated and more media is uploaded, that project would then contain some media in the default bucket and some in the newly defined bucket.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a bucket.

Request Body schema: application/json
archive_sc
string
Enum: "STANDARD" "DEEP_ARCHIVE" "COLDLINE"

Storage class in which archived objects live.

BucketGCPConfig (object) or BucketOCIConfig (object) or BucketS3Config (object)

JSON string containing cloud storage credentials.

external_host
string

The proxy host for presigned urls.

live_sc
string
Value: "STANDARD"

Storage class in which live objects live.

name
string

Bucket name.

store_type
string
Enum: "AWS" "MINIO" "GCP" "OCI"

Type of object store on which the bucket is hosted.

Responses

Request samples

Content type
application/json
{
  • "name": "my-other-bucket"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetBucketList

Get bucket list.

Buckets allow users to specify a project-specific S3 bucket to store media. Buckets are defined at the Organization level. Creating and setting a bucket on a project requires administrative access within the organization. Once a bucket is defined for a project, all media subsequently uploaded to that project will be stored in the bucket. Projects may have media in multiple buckets. For example, if a project is initially created without setting a separate bucket and media is uploaded, then the bucket field is updated and more media is uploaded, that project would then contain some media in the default bucket and some in the newly defined bucket.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateBucket

Create bucket.

Buckets allow users to specify a project-specific S3 bucket to store media. Buckets are defined at the Organization level. Creating and setting a bucket on a project requires administrative access within the organization. Once a bucket is defined for a project, all media subsequently uploaded to that project will be stored in the bucket. Projects may have media in multiple buckets. For example, if a project is initially created without setting a separate bucket and media is uploaded, then the bucket field is updated and more media is uploaded, that project would then contain some media in the default bucket and some in the newly defined bucket.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Request Body schema: application/json
archive_sc
string
Enum: "STANDARD" "DEEP_ARCHIVE" "COLDLINE"

Storage class in which archived objects live.

required
BucketGCPConfig (object) or BucketOCIConfig (object) or BucketS3Config (object)

JSON string containing cloud storage credentials.

external_host
string

The proxy host for presigned urls.

live_sc
string
Value: "STANDARD"

Storage class in which live objects live.

name
required
string

Bucket name.

store_type
required
string
Enum: "AWS" "MINIO" "GCP" "OCI"

Type of object store on which the bucket is hosted.

Responses

Request samples

Content type
application/json
{
  • "config": {
    },
  • "name": "my-bucket",
  • "store_type": "AWS"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

GetChangeLogList

Get a list of change logs.

A ChangeLog is the object containing information about a change applied to an object. It includes the time, user, and description of the change.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
user_id
integer

Filters ChangeLogs for the given user.

entity_id
integer

Filters ChangeLogs for the given entity.

entity_type
string
Enum: "media" "localization" "state" "leaf"

Filters ChangeLogs for the given entity type.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CloneMediaList

Clone media list.

This method copies media to a different project without copying the underlying files. It accepts the same query parameters as a Media GET request. All media matching the query will be copied to the project, media type, and section in the given request body. Section is passed as a section name; if the given section does not exist, it will be created.

This endpoint will only clone up to 500 media per request. Use the start, stop, or after parameters to paginate a request.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying the source project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
Request Body schema: application/json
dest_project
required
integer

Unique integer identifying destination project.

dest_section
string or null

Destination media section name.

dest_type
required
integer >= -1

Unique integer identifying destination media type. Use -1 to automatically select the media type if only one media type exists in the destination project.

Responses

Request samples

Content type
application/json
{
  • "dest_project": 1,
  • "dest_section": "My section",
  • "dest_type": 1
}

Response samples

Content type
application/json
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

GetDownloadInfo

Retrieve URL for one or more file downloads from a given project.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
expiration
integer [ 1 .. 86400 ]
Default: 86400

Number of seconds until URL expires and becomes invalid.

Request Body schema: application/json
keys
required
Array of strings

Array of object keys for download info retrieval.

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

SendEmail

Send an email message using the Tator AWS SES configured credentials.'

Messages can only be sent to members of the same project.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
Array of objects (EmailAttachmentSpec)

S3 object(s) to send as attachment(s). Ensure the attachment size does not exceed the corresponding email service limits

recipients
required
Array of strings

Recipients of the email message. They must be members of this project. Entries are either in "Name email@email.com" or "email@email.com" format

subject
required
string

Subject of the email message

text
required
string

Text body of the email message. HTML is currently not supported.

Responses

Request samples

Content type
application/json
{
  • "attachments": [
    ],
  • "recipients": [
    ],
  • "subject": "string",
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteFavorite

Delete favorite.

Favorites are saved annotation values to help speed up annotation. They are scoped to a project and user, so if a user requests Favorites for a project they will only receive the Favorites created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a favorite.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetFavorite

Get favorite.

Favorites are saved annotation values to help speed up annotation. They are scoped to a project and user, so if a user requests Favorites for a project they will only receive the Favorites created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a favorite.

Responses

Response samples

Content type
application/json
{
  • "entity_type_name": "Localization",
  • "id": 0,
  • "name": "string",
  • "page": 1,
  • "type": 0,
  • "user": 1,
  • "values": { }
}

UpdateFavorite

Update favorite.

Favorites are saved annotation values to help speed up annotation. They are scoped to a project and user, so if a user requests Favorites for a project they will only receive the Favorites created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a favorite.

Request Body schema: application/json
entity_type_name
string
Enum: "Localization" "State"

Name of entity type associated with the favorite

name
string

Name of the favorite.

Responses

Request samples

Content type
application/json
{
  • "entity_type_name": "Localization",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetFavoriteList

Get favorite list.

Favorites are saved annotation values to help speed up annotation. They are scoped to a project and user, so if a user requests Favorites for a project they will only receive the Favorites created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateFavorite

Create favorite.

Favorites are saved annotation values to help speed up annotation. They are scoped to a project and user, so if a user requests Favorites for a project they will only receive the Favorites created by them.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
entity_type_name
string
Enum: "Localization" "State"

Name of entity type associated with the favorite

name
string

Name of the favorite.

page
integer [ 1 .. 10 ]
Default: 1

Integer specifying page to display on. Should be 1-10.

type
integer >= 1

Unique integer identifying an entity type.

object

Attribute name/value pairs.

Responses

Request samples

Content type
application/json
{
  • "entity_type_name": "Localization",
  • "name": "string",
  • "page": 1,
  • "type": 1,
  • "values": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteFile

Delete registered non-media File object

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered File object.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetFile

Get registered non-media File object

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered File object.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "created_by": 0,
  • "created_datetime": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "elemental_id": "string",
  • "id": 0,
  • "modified_by": 0,
  • "modified_datetime": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "path": "string",
  • "project": 0,
  • "type": 0
}

UpdateFile

Updated registered non-media File object

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered File object.

Request Body schema: application/json
object

Object containing attribute values

description
string

Description of file

elemental_id
string or null

The elemental ID of the object.

name
string

Name of file

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

path
string

Relative URL to the file

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

type
integer

Unique integer identifying FileType of this File object.

Responses

Request samples

Content type
application/json
{
  • "name": "New file name"
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

DeleteFileType

Delete file type.

A file type is the metadata definition object for non-media FIle objects. It includes the name, description, and any associated user defined attributes.

Note that this will also delete any files associated with the file type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an file type.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetFileType

Get file type.

A file type is the metadata definition object for non-media FIle objects. It includes the name, description, and any associated user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an file type.

Responses

Response samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "description": "",
  • "elemental_id": "string",
  • "id": 0,
  • "name": "string",
  • "project": 0
}

UpdateFileType

Update file type.

A file type is the metadata definition object for non-media FIle objects. It includes the name, description, and any associated user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an file type.

Request Body schema: application/json
description
string
Default: ""

Description of the file type.

elemental_id
string or null

The elemental ID of the object.

name
string

Name of the file type.

Responses

Request samples

Content type
application/json
{
  • "description": "New description",
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetFileTypeList

Get file type list.

A file type is the metadata definition object for non-media FIle objects. It includes the name, description, and any associated user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateFileType

Create file type.

A file type is the metadata definition object for non-media FIle objects. It includes the name, description, and any associated user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
Array of objects (AttributeType)

Attribute type definitions.

description
string
Default: ""

Description of the file type.

elemental_id
string or null

The elemental ID of the object.

name
string

Name of the file type.

Responses

Request samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "name": "My file type"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

GetFileList

Get non-media associated File object list.

Non-media assocaited files can be stored within the project along with user-defined attributes. Unlike temporary files, these are permanent. These do not include applet files and algorithm workflow files.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a FileType.

name
string

Name of the file.

after
integer

If given, all results returned will be after the File object with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateFile

Create generic, non-media associated File object.

Non-media assocaited files can be stored within the project along with user-defined attributes. Unlike temporary files, these are permanent. These do not include applet files and algorithm workflow files.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
object

Object containing attribute values

description
string

Description of file

elemental_id
string or null

The elemental ID of the object.

name
string

Name of file

type
integer

Unique integer identifying FileType of this File object.

user_elemental_id
string or null

The elemental ID of the object.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "description": "string",
  • "elemental_id": "string",
  • "name": "string",
  • "type": 0,
  • "user_elemental_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

GetClip

Get video clip.

Facility to get a clip from the server. Returns a temporary file object that expires in 24 hours.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
frame_ranges
required
Array of strings
Example: frame_ranges=0:30,50:90

Comma-seperated list of frame ranges to capture.

quality
integer >= 0

Source resolution to use (default to highest quality)

reencode
integer >= 0

Re-encode to a h264 codec (assumes veryfast) profile (>0 = true, 0 == false)

Responses

Response samples

Content type
application/json
{
  • "file": {
    },
  • "segment_end_frames": [
    ],
  • "segment_start_frames": [
    ]
}

GetClonedMedia

Get cloned media.

This method finds and returns the list of media ids that are clones of the given id.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

Responses

Response samples

Content type
application/json
{
  • "ids": [
    ],
  • "message": "string"
}

GetFrame

Get frame(s) from a video.

Facility to get a frame(jpg/png) of a given video frame, returns a square tile of frames based on the input parameter.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
frames
Array of integers <= 32 characters [ items >= 0 ]
Default: [0]
Example: frames=0,100,200

Comma-seperated list of frames to capture.

tile
string

wxh, if not supplied is made as squarish as possible.

roi
string

w:h:x:y, optionally crop each frame to a given roi in relative coordinates.

force_scale
string

Size of each frame image to return in format wxh. This forces scaling the image. Applied after ROI crop if any.Default is the size of the frame for highest streaming resolution. Example: 1024x768

animate
integer [ 0 .. 15 ]

If not tiling, animate each frame at a given fps in a gif.

quality
integer >= 0

Source resolution to use (default to highest quality)

Responses

Request samples 

# Downloads a graphic and puts it in a persistent path
tmp_path = api.get_localization_graphic(id)
os.move(tmp_path, persistent_path)

DeleteImageFile

Delete image file.

Image files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying image. One or more image files can be used to reference thumbnails, thumbnail GIFs, or images in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the image file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "image" "thumbnail" "thumbnail_gif"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of images for the specified role.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetImageFile

Get image file.

Image files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying image. One or more image files can be used to reference thumbnails, thumbnail GIFs, or images in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the image file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "image" "thumbnail" "thumbnail_gif"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of images for the specified role.

Responses

Response samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "path": "string",
  • "resolution": [
    ],
  • "size": 0
}

UpdateImageFile

Update image file.

Image files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying image. One or more image files can be used to reference thumbnails, thumbnail GIFs, or images in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the image file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "image" "thumbnail" "thumbnail_gif"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of images for the specified role.

Request Body schema: application/json
host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

mime
string

Example mime: "image/jpg".

path
required
string

Relative URL to the file.

resolution
required
Array of integers = 2 items [ items >= 1 ]

Resolution of the video in pixels (height, width).

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "path": "string",
  • "resolution": [
    ],
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetImageFileList

Get image file list.

Image files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying image. One or more image files can be used to reference thumbnails, thumbnail GIFs, or images in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the image file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "image" "thumbnail" "thumbnail_gif"

Role of media file being referenced.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateImageFile

Create image file.

Image files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying image. One or more image files can be used to reference thumbnails, thumbnail GIFs, or images in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the image file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "image" "thumbnail" "thumbnail_gif"

Role of media file being referenced.

index
integer >= 0

Insertion index. Must be less than size of current list of images for the specified role. If omitted, the image file will be appended to the end of the list.

Request Body schema: application/json
host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

mime
string

Example mime: "image/jpg".

path
required
string

Relative URL to the file.

resolution
required
Array of integers = 2 items [ items >= 1 ]

Resolution of the video in pixels (height, width).

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "http_auth": "string",
  • "mime": "string",
  • "path": "string",
  • "resolution": [
    ],
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteInvitation

Delete invitation.

Invitations allow users with administrative privileges for an organization to invite a user to join their organization using their email address. Upon creation, if automatic emails are configured an email will be sent to the specified email address. If the user has not yet registered, the email will contain a link to register using a registration token. If the user has registered, the email will send a link to accept the invitation. The link is also returned in the response of the create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a invitation.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetInvitation

Get invitation.

Invitations allow users with administrative privileges for an organization to invite a user to join their organization using their email address. Upon creation, if automatic emails are configured an email will be sent to the specified email address. If the user has not yet registered, the email will contain a link to register using a registration token. If the user has registered, the email will send a link to accept the invitation. The link is also returned in the response of the create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a invitation.

Responses

Response samples

Content type
application/json
{
  • "created_by": 0,
  • "created_datetime": "2019-08-24T14:15:22Z",
  • "created_username": "string",
  • "email": "string",
  • "id": 0,
  • "organization": 1,
  • "permission": "Member",
  • "registration_token": "string",
  • "status": "Pending"
}

UpdateInvitation

Update invitation.

Invitations allow users with administrative privileges for an organization to invite a user to join their organization using their email address. Upon creation, if automatic emails are configured an email will be sent to the specified email address. If the user has not yet registered, the email will contain a link to register using a registration token. If the user has registered, the email will send a link to accept the invitation. The link is also returned in the response of the create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a invitation.

Request Body schema: application/json
permission
string
Enum: "Member" "Admin"

User permission level for the organization.

status
string
Value: "Accepted"

Status of the invitation.

Responses

Request samples

Content type
application/json
{
  • "permission": "Member",
  • "status": "Accepted"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetInvitationList

Get invitation list.

Invitations allow users with administrative privileges for an organization to invite a user to join their organization using their email address. Upon creation, if automatic emails are configured an email will be sent to the specified email address. If the user has not yet registered, the email will contain a link to register using a registration token. If the user has registered, the email will send a link to accept the invitation. The link is also returned in the response of the create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateInvitation

Create invitation.

Invitations allow users with administrative privileges for an organization to invite a user to join their organization using their email address. Upon creation, if automatic emails are configured an email will be sent to the specified email address. If the user has not yet registered, the email will contain a link to register using a registration token. If the user has registered, the email will send a link to accept the invitation. The link is also returned in the response of the create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

Request Body schema: application/json
email
required
string

Email address of invitee.

permission
required
string
Enum: "Member" "Admin"

User permission level for the organization.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "permission": "Member"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteJob

Delete background job.

Algorithms create argo workflows that are annotated with two uuid1 strings, one identifying the run and the other identifying the group. Jobs that are submitted together have the same group id, but each workflow has a unique run id.

This method allows the user to cancel a job using the uid returned by Job create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
uid
required
string

A uuid1 string identifying to single Job.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetJob

Get background job.

Algorithms create argo workflows that are annotated with two uuid1 strings, one identifying the run and the other identifying the group. Jobs that are submitted together have the same group id, but each workflow has a unique run id.

This method allows the user to get a job's status using the uid returned by Job create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
uid
required
string

A uuid1 string identifying to single Job.

Responses

Response samples

Content type
application/json
{
  • "gid": "string",
  • "id": "string",
  • "nodes": [
    ],
  • "project": 0,
  • "start_time": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "stop_time": "2019-08-24T14:15:22Z",
  • "uid": "string",
  • "user": 0
}

DeleteJobCluster

Delete registered job cluster

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered job cluster.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetJobCluster

Get registered job cluster

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered job cluster.

Responses

Response samples

Content type
application/json
{
  • "cert": "string",
  • "host": "string",
  • "id": 0,
  • "name": "string",
  • "organization": 0,
  • "port": 0,
  • "token": "string"
}

UpdateJobCluster

Updated registered job cluster

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a registered job cluster.

Request Body schema: application/json
cert
required
string

Certificate for accessing the job cluster.

host
required
string

Hostname where the cluster can be accessed.

name
required
string

Unique name of the job cluster.

port
required
integer

Port where the cluster can be accessed.

token
required
string

Token for accessing the job cluster.

Responses

Request samples

Content type
application/json
{
  • "host": "New hostname",
  • "name": "New unique name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetJobClusterList

Get job clusters.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateJobCluster

Create a job cluster.

This endpoint replicates the job cluster creation through the admin portal.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an organization.

Request Body schema: application/json
cert
required
string

Certificate for accessing the job cluster.

host
required
string

Hostname where the cluster can be accessed.

name
required
string

Unique name of the job cluster.

port
required
integer

Port where the cluster can be accessed.

token
required
string

Token for accessing the job cluster.

Responses

Request samples

Content type
application/json
{
  • "cert": "string",
  • "host": "string",
  • "name": "string",
  • "port": 0,
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteJobList

Delete background job list.

Algorithms create argo workflows that are annotated with two uuid1 strings, one identifying the run and the other identifying the group. Jobs that are submitted together have the same group id, but each workflow has a unique run id.

This method allows the user to batch delete a list of jobs.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
gid
string

A UUID string identifying a group of jobs.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetJobList

Get background job list.

Algorithms create argo workflows that are annotated with two uuid1 strings, one identifying the run and the other identifying the group. Jobs that are submitted together have the same group id, but each workflow has a unique run id.

This method allows the user to status for a list of jobs in a project.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
gid
string

A UUID string identifying a group of jobs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateJobList

Launch a registered algorithm.

This will create one or more Argo workflows that execute the named algorithm registration. To get a list of available algorithms, use the Algorithms endpoint. A media list will be submitted for processing using either a query string or a list of media IDs. If neither are included, the algorithm will be launched on all media in the project.

Media is divided into batches based on the files_per_job field of the Algorithm object. One batch is submitted to each Argo workflow.

Submitted algorithm jobs may be cancelled via the Job or JobGroup endpoints.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
algorithm_name
required
string

Name of the algorithm to execute.

Array of objects (AlgorithmParameter)

Extra parameters to pass into the algorithm

object or null

Send an email message to members of the project using the Tator configured AWS email service

media_ids
required
Array of integers

List of media IDs.

object or null

Send an email message to members of the project using the Tator configured AWS email service

Responses

Request samples

Content type
application/json
Example
{
  • "algorithm_name": "My Algorithm",
  • "media_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

DeleteLeaf

Delete leaf.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a leaf.

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

GetLeaf

Get leaf.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a leaf.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "id": 0,
  • "name": "string",
  • "parent": 0,
  • "path": "string",
  • "project": 0,
  • "type": 0
}

UpdateLeaf

Update leaf.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a leaf.

Request Body schema: application/json
object

Attribute values to update.

name
string

Name of the leaf.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "name": "string",
  • "null_attributes": [
    ],
  • "reset_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLeafCount

Get leaf list count.

This endpoint accepts the same query parameters as a GET or PUT request to the Leaves endpoint, but only returns the number of leaves.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |

Responses

Response samples

Content type
application/json
0
0

GetLeafCountById

Get leaf list count by ID.

This endpoint accepts the same query parameters as a GET or PUT request to the Leaves endpoint, but only returns the number of leaves.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of leaf IDs to retrieve.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "object_search": {
    }
}

Response samples

Content type
application/json
0
0

DeleteLeafType

Delete leaf type.

A leaf type is the metadata definition object for a leaf. It includes name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an leaf type.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLeafType

Get leaf type.

A leaf type is the metadata definition object for a leaf. It includes name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an leaf type.

Responses

Response samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "description": "",
  • "dtype": "string",
  • "elemental_id": "string",
  • "id": 0,
  • "name": "string",
  • "project": 0
}

UpdateLeafType

Update leaf type.

A leaf type is the metadata definition object for a leaf. It includes name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an leaf type.

Request Body schema: application/json
description
string

Description of the leaf type.

elemental_id
string or null

The elemental ID of the object.

name
string

Name of the leaf type.

Responses

Request samples

Content type
application/json
{
  • "description": "New description",
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLeafTypeList

Get leaf type list.

A leaf type is the metadata definition object for a leaf. It includes name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateLeafType

Create leaf type.

A leaf type is the metadata definition object for a leaf. It includes name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
Array of objects (AttributeType)

Attribute type definitions.

description
string
Default: ""

Description of the leaf type.

elemental_id
string or null

The elemental ID of the object.

name
string

Name of the leaf type.

Responses

Request samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "name": "My leaf type"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

LeafSuggestion

Get list of autocomplete suggestions.

This endpoint is compatible with devbridge suggestion format . It performs a glob search on leaf objects in the project.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

ancestor
required
string

Get descendents of a leaf element (inclusive), by path (i.e. ITIS.Animalia).

query Parameters
min_level
integer

Integer specifying level of results that may be returned. For example, 2 refers to grandchildren of the level specified by the ancestor parameter.

query
required
string

String to search for matching names.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

DeleteLeafList

Delete leaf list.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

This method performs a bulk delete on all leaves matching a query. It is recommended to use a GET request first to check what is being deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of leaf IDs to retrieve.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "object_search": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLeafList

Get leaf list.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |

Responses

Response samples

Content type
application/json
[
  • {
    }
]

UpdateLeafList

Update leaf list.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

This method does a bulk update on all leaves matching a query. Only user-defined attributes may be bulk updated.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
Request Body schema: application/json
object

Attribute values to bulk update an entity list.

Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of leaf IDs to retrieve.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "float_array": [
    ],
  • "ids": [
    ],
  • "null_attributes": [
    ],
  • "object_search": {
    },
  • "reset_attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CreateLeafList

Create leaf list.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

This method does a bulk create on a list of :class:tator.models.LeafSpec objects; it also accepts a single instance. A maximum of 500 leaves may be created in one request.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
One of
<= 500 items
Array (<= 500 items)
object

Object containing attribute values.

name
required
string

Name of the leaf.

parent
integer or null

ID to use as parent if there is one.

type
required
integer

Unique integer identifying a leaf type.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "name": "string",
  • "parent": 0,
  • "type": 0
}

Response samples

Content type
application/json
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

GetLeafListById

Get leaf list by ID.

Leaves are used to define label hierarchies that can be used for autocompletion of string attribute types. Leaves are a type of entity in Tator, meaning they can be described by user-defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
type
integer

Unique integer identifying a leaf type.

name
string

Name of the leaf element.

depth
integer

Get a specific tree depth. Root node depth is 0.

leaf_id
Array of integers

Comma-separated list of leaf IDs.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of leaf IDs to retrieve.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "object_search": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

DeleteLocalization

Delete localization.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization.

Request Body schema: application/json
prune
integer [ 0 .. 1 ]
Default: 0

If set to 1 will purge the object from the database entirely. This removes any record, change-log, that this metadatum ever existed.

Responses

Request samples

Content type
application/json
{
  • "prune": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLocalization

Get localization.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "created_by": 0,
  • "created_datetime": "2019-08-24T14:15:22Z",
  • "elemental_id": "string",
  • "frame": 0,
  • "height": 1,
  • "id": 0,
  • "media": 0,
  • "modified_by": 0,
  • "modified_datetime": "2019-08-24T14:15:22Z",
  • "parent": 0,
  • "points": [
    ],
  • "project": 0,
  • "thumbnail_image": "string",
  • "type": 0,
  • "u": -1,
  • "user": 0,
  • "v": -1,
  • "variant_deleted": true,
  • "version": 0,
  • "width": 1,
  • "x": 1,
  • "y": 1
}

UpdateLocalization

Update localization.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization.

Request Body schema: application/json
object

Object containing attribute values.

elemental_id
string or null

The elemental ID of the object.

frame
integer

Frame number of this localization if it is in a video.

height
number or null [ 0 .. 1 ]

Normalized height of bounding box for box localization types.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

parent
number or null

If a clone, the pk of the parent.

points
Array of numbers or null

List of normalized [x, y] pairs for poly localization types.

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

u
number or null [ -1 .. 1 ]

Horizontal vector component for line localization types.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

v
number or null [ -1 .. 1 ]

Vertical vector component for line localization types.

width
number or null [ 0 .. 1 ]

Normalized width of bounding box for box localization types.

x
number or null [ 0 .. 1 ]

Normalized horizontal position of left edge of bounding box for box localization types, start of line for line localization types, or position of dot for dot localization types.

y
number or null [ 0 .. 1 ]

Normalized vertical position of top edge of bounding box for box localization types, start of line for line localization types, or position of dot for dot localization types.

Responses

Request samples

Content type
application/json
{
  • "height": 0.25,
  • "width": 0.25,
  • "x": 0.25,
  • "y": 0.25
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLocalizationCount

Get localization list count.

This endpoint accepts the same query parameters as a GET or PUT request to the Localizations endpoint, but only returns the number of localizations.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
0
0

GetLocalizationCountById

Get localization list count by ID.

This endpoint accepts the same query parameters as a GET or PUT request to the Localizations endpoint, but only returns the number of localizations.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of localization IDs to retrieve.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which localizations should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of parent state IDs for which localizations should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
0
0

GetLocalizationGraphic

Get localization graphic from a media object.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization.

query Parameters
force_scale
string

Size of final image to return. This forces scaling the image. Default is the localization size and margins define the image size. Example: 100x100

use_default_margins
boolean
Default: true

Use default margins for localization types. Default margins (x,y pixels) - dot: (10,10) line: (10,10) box: (0,0)

margin_x
integer

Pixel margin to apply to the height of the localization when generating the image. Valid only if use_default_margins is false.

margin_y
integer

Pixel margin to apply to the width of the localization when generating the image. Valid only if use_default_margins is false.

Responses

DeleteLocalizationType

Delete localization type.

A localization type is the metadata definition object for a localization. It includes shape, name, description, and may have any number of user-defined attribute types associated with it.

Note that this will also delete any localizations associated with the localization type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization type.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLocalizationType

Get localization type.

A localization type is the metadata definition object for a localization. It includes shape, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization type.

Responses

Response samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "color_map": {
    },
  • "description": "string",
  • "drawable": true,
  • "dtype": "box",
  • "elemental_id": "string",
  • "grouping_default": true,
  • "id": 0,
  • "line_width": 1,
  • "media": [
    ],
  • "name": "string",
  • "project": 0,
  • "visible": true
}

UpdateLocalizationType

Update localization type.

A localization type is the metadata definition object for a localization. It includes shape, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a localization type.

Request Body schema: application/json
object or null (ColorMap)

Maps an attribute value or version to a color/alpha. Use key and map (optionally alpha_ranges) to map an attribute value to colors. Use version to map version IDs to colors.

description
string

Description of the localization type.

drawable
boolean
Default: true

Whether this type can be drawn in the UI. Must also be visible.

elemental_id
string or null

The elemental ID of the object.

grouping_default
boolean
Default: true

Whether to group elements in the UI by default.

line_width
integer >= 1

Width of the line used to draw the localization.

name
string

Name of the localization type.

visible
boolean
Default: true

Whether this type should be displayed in the UI.

Responses

Request samples

Content type
application/json
{
  • "description": "New description",
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLocalizationTypeList

Get localization type list.

A localization type is the metadata definition object for a localization. It includes shape, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

List of unique integers identifying a media.

type
integer

Deprecated. Use LocalizationType endpoint to retrieve individual localization type by ID.

elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateLocalizationType

Create localization type.

A localization type is the metadata definition object for a localization. It includes shape, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
Array of objects (AttributeType)

Attribute type definitions.

object or null (ColorMap)

Maps an attribute value or version to a color/alpha. Use key and map (optionally alpha_ranges) to map an attribute value to colors. Use version to map version IDs to colors.

description
string

Description of the localization type.

drawable
boolean
Default: true

Whether this type can be drawn in the UI. Must also be visible.

dtype
required
string
Enum: "box" "line" "dot" "poly"

Shape of this localization type.

elemental_id
string or null

The elemental ID of the object.

grouping_default
boolean
Default: true

Whether to group elements in the UI by default.

line_width
integer >= 1

Width of the line used to draw the localization.

media_types
required
Array of integers non-empty [ items >= 1 ]

List of integers identifying media types that this localization type may apply to.

name
required
string

Name of the localization type.

visible
boolean
Default: true

Whether this type should be displayed in the UI.

Responses

Request samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "dtype": "box",
  • "media_types": [
    ],
  • "name": "My localization type"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteLocalizationList

Delete localiazation list.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

This method performs a bulk delete on all localizations matching a query. It is recommended to use a GET request first to check what is being deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of localization IDs to retrieve.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which localizations should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
prune
integer [ 0 .. 1 ]
Default: 0

If set to 1 will purge the object from the database entirely. This removes any record, change-log, that this metadatum ever existed.

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

state_ids
Array of integers[ items >= 1 ]

Array of parent state IDs for which localizations should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "null_attributes": [
    ],
  • "object_search": {
    },
  • "prune": 0,
  • "reset_attributes": [
    ],
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetLocalizationList

Get localization list.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
[
  • {
    }
]

UpdateLocalizationList

Update localiazation list.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

This method does a bulk update on all localizations matching a query. Only user-defined attributes may be bulk updated.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
object

Attribute values to bulk update an entity list.

Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of localization IDs to retrieve.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which localizations should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

new_elemental_id
string

The new elemental ID for these objects

new_version
integer

Unique integer identifying a new version for these objects

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of parent state IDs for which localizations should be retrieved.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CreateLocalizationList

Create localiazation list.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

This method does a bulk create on a list of :class:tator.models.LocalizationSpec objects; it also accepts a single instance. A maximum of 500 localizations may be created in one request.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
One of
<= 500 items
Array (<= 500 items)
object

Object containing attribute values.

elemental_id
string or null

The elemental ID of the object.

frame
required
integer

Frame number of this localization if it is in a video.

height
number or null [ 0 .. 1 ]

Normalized height of bounding box for box localization types.

media_id
required
integer

Unique integer identifying a media.

parent
number or null

If a clone, the pk of the parent.

points
Array of numbers or null

List of normalized [x, y] pairs for poly localization types.

type
required
integer

Unique integer identifying a localization type.

u
number or null [ -1 .. 1 ]

Horizontal vector component for line localization types.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

v
number or null [ -1 .. 1 ]

Vertical vector component for line localization types.

version
integer

Unique integer identifying the version.

width
number or null [ 0 .. 1 ]

Normalized width of bounding box for box localization types.

x
number or null [ 0 .. 1 ]

Normalized horizontal position of left edge of bounding box for box localization types, start of line for line localization types, or position of dot for dot localization types.

y
number or null [ 0 .. 1 ]

Normalized vertical position of top edge of bounding box for box localization types, start of line for line localization types, or position of dot for dot localization types.

Responses

Request samples

Content type
application/json
Example
{
  • "My First Attribute": "value1",
  • "My Second Attribute": "value2",
  • "frame": 1000,
  • "height": 0.4,
  • "media_id": 1,
  • "type": 1,
  • "width": 0.3,
  • "x": 0.1,
  • "y": 0.2
}

Response samples

Content type
application/json
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

GetLocalizationListById

Get localization list by ID.

Localizations are shape annotations drawn on a video or image. Available shapes (dtype) are box, line, or dot. Each shape is parameterized by a different subset of data members:

  • box uses x, y, width, height.
  • line uses x, y, u, v.
  • dot uses x and y.
  • poly uses points.

Geometry members may be left null when creating a localization, in which case the shapes may be drawn later using the redraw capability in the web UI. Localizations are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
frame
integer >= 0

Frame number of this localization if it is in a video.

related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of localization IDs to retrieve.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which localizations should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of parent state IDs for which localizations should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

DeleteMedia

Delete media.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMedia

Get media.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media.

query Parameters
presigned
integer [ 1 .. 86400 ]

If given, all path fields in media_files will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

no_cache
boolean

If True, and presigned is specified, a new presigned url will be generated.

Responses

Response samples

Content type
application/json
{
  • "archive_state": "archived",
  • "archive_status_date": "2019-08-24T14:15:22Z",
  • "attributes": {
    },
  • "codec": "string",
  • "created_by": 0,
  • "created_datetime": "string",
  • "elemental_id": "string",
  • "fps": 0,
  • "gid": "string",
  • "height": 0,
  • "id": 0,
  • "incident": 0,
  • "last_edit_end": "2019-08-24T14:15:22Z",
  • "last_edit_start": "2019-08-24T14:15:22Z",
  • "md5": "string",
  • "media_files": {
    },
  • "modified_by": 0,
  • "modified_datetime": "string",
  • "name": "string",
  • "num_frames": 0,
  • "project": 0,
  • "summary_level": 0,
  • "type": 0,
  • "uid": "string",
  • "width": 0
}

UpdateMedia

Update media.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media.

Request Body schema: application/json
archive_state
string
Enum: "to_archive" "to_live"

Marks media for archival or retrieval. Media may not be set directly to live or archived, the system performs that transition for the user.

object

Object containing attribute values.

codec
string

Codec of the original video.

Array of objects (ConcatDefinition)

List of concated videos

elemental_id
string

Unique ID of an element

fps
number

Frame rate of the video.

height
integer

Pixel height of the video.

last_edit_end
string <date-time>

Datetime of the end of the session when this media or its annotations were last edited.

last_edit_start
string <date-time>

Datetime of the start of the session when this media or its annotations were last edited.

object (LiveUpdateDefinition)
object (MediaFiles)

Object containing upload urls for the transcoded file and corresponding VideoDefinition.

object (MultiDefinition)

Object containing information needed for a multi media type.

name
string

Name of the media.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

num_frames
integer >= 0

Number of frames in the video.

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

summary_level
integer

If supplied, this video is best summarized at this frame interval

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

width
integer

Pixel width of the video.

Responses

Request samples

Content type
application/json
{
  • "archive_state": "to_archive",
  • "attributes": {
    },
  • "codec": "string",
  • "concat": [
    ],
  • "elemental_id": "string",
  • "fps": 0,
  • "height": 0,
  • "last_edit_end": "2019-08-24T14:15:22Z",
  • "last_edit_start": "2019-08-24T14:15:22Z",
  • "live": {
    },
  • "media_files": {
    },
  • "multi": {
    },
  • "name": "string",
  • "null_attributes": [
    ],
  • "num_frames": 0,
  • "reset_attributes": [
    ],
  • "summary_level": 0,
  • "user_elemental_id": "string",
  • "width": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMediaCount

Get media list count.

This endpoint accepts the same query parameters as a GET or PUT request to the Medias endpoint, but only returns the number of media.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
0
0

GetMediaCountById

Get media list count by ID.

This endpoint accepts the same query parameters as a GET or PUT request to the Medias endpoint, but only returns the number of media.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
0
0

GetMediaNext

Retrieve ID of next media in a media list.

This endpoint accepts the same query parameters as a GET request to the Medias endpoint, but only returns the next media ID from the media passed as a path parameter. This allows iteration through a media list without serializing the entire list, which may be large.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
{
  • "next": 0
}

GetMediaPrev

Retrieve ID of previous media in a media list.

This endpoint accepts the same query parameters as a GET request to the Medias endpoint, but only returns the previous media ID from the media passed as a path parameter. This allows iteration through a media list without serializing the entire list, which may be large.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
{
  • "prev": 0
}

GetMediaStats

Retrieve count, download size, total size, and duration of a media list.

This endpoint accepts the same query parameters as a GET request to the Medias endpoint, but only returns statistics about the media.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "download_size": 0,
  • "duration": 0,
  • "total_size": 0
}

DeleteMediaType

Delete media type.

A media type is the metadata definition object for media. It includes file format, name, description, and may have any number of user defined attribute types associated with it.

Note that this will also delete any media associated with the media type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an media type.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMediaType

Get media type.

A media type is the metadata definition object for media. It includes file format, name, description, and may have any number of user defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an media type.

Responses

Response samples

Content type
application/json
{
  • "archive_config": [
    ],
  • "attribute_types": [
    ],
  • "default_box": 0,
  • "default_dot": 0,
  • "default_line": 0,
  • "default_volume": 100,
  • "description": "",
  • "dtype": "image",
  • "elemental_id": "string",
  • "file_format": "stri",
  • "id": 0,
  • "name": "string",
  • "overlay_config": { },
  • "project": 0,
  • "streaming_config": [
    ],
  • "visible": true
}

UpdateMediaType

Update media type.

A media type is the metadata definition object for media. It includes file format, name, description, and may have any number of user defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an media type.

Request Body schema: application/json
Array of objects (ArchiveConfig)

Archive config definitions. If null, the raw file will be uploaded to Tator.

default_box
integer

Unique integer identifying default box type for drawing.

default_dot
integer

Unique integer identifying default dot type for drawing.

default_line
integer

Unique integer identifying default line type for drawing.

default_volume
integer [ 0 .. 100 ]

Default audio volume for this media type.

description
string

Description of the media type.

elemental_id
string or null

The elemental ID of the object.

file_format
string <= 4 characters

File extension. If omitted, any recognized file extension for the given dtype is accepted for upload. Do not include a dot prefix.

name
string

Name of the media type.

Array of objects (ResolutionConfig)

Streaming config definition. If null, the default will be used.

visible
boolean

Visible configuration

Responses

Request samples

Content type
application/json
{
  • "description": "New description",
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMediaTypeList

Get media type list.

A media type is the metadata definition object for media. It includes file format, name, description, and may have any number of user defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateMediaType

Create media type.

A media type is the metadata definition object for media. It includes file format, name, description, and may have any number of user defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
Array of objects (ArchiveConfig)

Archive config definitions. If null, the raw file will be uploaded to Tator.

Array of objects (AttributeType)

Attribute type definitions.

default_box
integer

Unique integer identifying default box type for drawing.

default_dot
integer

Unique integer identifying default dot type for drawing.

default_line
integer

Unique integer identifying default line type for drawing.

default_volume
integer [ 0 .. 100 ]

Default audio volume for this media type.

description
string
Default: ""

Description of the media type.

dtype
required
string
Enum: "image" "video" "multi" "live"

Type of the media, image or video.

elemental_id
string or null

The elemental ID of the object.

file_format
string <= 4 characters

File extension. If omitted, any recognized file extension for the given dtype is accepted for upload. Do not include a dot prefix.

name
required
string

Name of the media type.

object

Overlay configuration

Array of objects (ResolutionConfig)

Streaming config definition. If null, the default will be used.

visible
boolean

Visible configuration

Responses

Request samples

Content type
application/json
{
  • "attribute_types": [
    ],
  • "dtype": "video",
  • "name": "My media type"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteMediaList

Delete media list.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

This method performs a bulk delete on all media matching a query. It is recommended to use a GET request first to check what is being deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMediaList

Get media list.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

presigned
integer [ 1 .. 86400 ]

If given, all path fields in media_files will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

no_cache
boolean

If True, and presigned is specified, a new presigned url will be generated.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

UpdateMediaList

Update media list.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

This method does a bulk update on all media matching a query. Only user-defined attributes may be bulk updated.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
archive_state
string
Enum: "to_archive" "to_live"

Marks media for archival or retrieval. Media may not be set directly to live or archived, the system performs that transition for the user.

object

Attribute values to bulk update an entity list.

Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CreateMediaList

Create media list.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

This method creates a Media object in the database for each :class:tator.models.MediaSpec in body. body must be a list or single instance of :class:tator.models.MediaSpec. For images, the media must already be uploaded and an upload URL must be provided, as well as the group and job IDs associated with the upload. For videos, it is recommended to use the Transcode endpoint, which will create the media object itself. This method is only needed for local transcodes. In that case, it will create an empty Media object; thumbnails, streaming, and archival videos must be subsequently uploaded and saved via the Media PATCH method.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
One of
<= 500 items
Array (<= 500 items)
object or null

Object containing attribute values.

codec
string or null

Codec for videos.

elemental_id
string

Unique ID of an element

fps
number or null

Frame rate for videos.

gid
string

Group ID for the upload group of this media.

height
integer or null

Vertical resolution in pixels.

md5
required
string

MD5 sum of the media file.

name
required
string

Name of the file.

num_frames
integer or null

Number of frames for videos.

reference_only
integer <= 1
Default: 0

Do not import the media resources into Tator. This causes the image to be accessed at the supplied URL upon access in the UI. Valid for images only.

section
required
string

Media section name.

summary_level
integer

If supplied, this video is best summarized at this frame interval

thumbnail_gif_url
string

Upload URL for the video gif thumbnail if already generated.

thumbnail_url
string

Upload URL for the media thumbnail if already generated.

type
required
integer >= -1

Unique integer identifying a media type. Use -1 to automatically select the media type if only one media type exists in a project.

uid
string

Unique ID for the upload of this media.

url
string

Upload URL for the image if this is an image type, URL of hosted original media if this is a video type. For video types this field is just for reference.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

width
integer or null

Horizontal resolution in pixels.

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    },
  • "codec": "string",
  • "elemental_id": "string",
  • "fps": 0,
  • "gid": "string",
  • "height": 0,
  • "md5": "string",
  • "name": "string",
  • "num_frames": 0,
  • "reference_only": 0,
  • "section": "string",
  • "summary_level": 0,
  • "thumbnail_gif_url": "string",
  • "thumbnail_url": "string",
  • "type": -1,
  • "uid": "string",
  • "url": "string",
  • "user_elemental_id": "string",
  • "width": 0
}

Response samples

Content type
application/json
Example
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

GetMediaListById

Get media list by ID.

A media may be an image or a video. Media are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

presigned
integer [ 1 .. 86400 ]

If given, all path fields in media_files will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

no_cache
boolean

If True, and presigned is specified, a new presigned url will be generated.

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

DeleteMembership

Delete membership.

Memberships specify a permission level of a user to a project. There are currently five cumulative permission levels:

  • View Only can only view a project and not change any data.
  • Can Edit can create, modify, and delete annotations.
  • Can Transfer can upload and download media.
  • Can Execute can launch algorithm workflows.
  • Full Control can change project settings, including inviting new members, project name, and project metadata schema.
Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a membership.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMembership

Get membership.

Memberships specify a permission level of a user to a project. There are currently five cumulative permission levels:

  • View Only can only view a project and not change any data.
  • Can Edit can create, modify, and delete annotations.
  • Can Transfer can upload and download media.
  • Can Execute can launch algorithm workflows.
  • Full Control can change project settings, including inviting new members, project name, and project metadata schema.
Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a membership.

Responses

Response samples

Content type
application/json
{
  • "default_version": 1,
  • "email": "string",
  • "first_name": "string",
  • "id": 0,
  • "last_name": "string",
  • "permission": "View Only",
  • "project": 0,
  • "user": 1,
  • "username": "string"
}

UpdateMembership

Update membership.

Memberships specify a permission level of a user to a project. There are currently five cumulative permission levels:

  • View Only can only view a project and not change any data.
  • Can Edit can create, modify, and delete annotations.
  • Can Transfer can upload and download media.
  • Can Execute can launch algorithm workflows.
  • Full Control can change project settings, including inviting new members, project name, and project metadata schema.
Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a membership.

Request Body schema: application/json
default_version
integer >= 1

Unique integer identifying a version.

permission
string
Enum: "View Only" "Can Edit" "Can Transfer" "Can Execute" "Full Control"

User permission level for the project.

Responses

Request samples

Content type
application/json
{
  • "permission": "View Only"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetMembershipList

Get membership list.

Memberships specify a permission level of a user to a project. There are currently five cumulative permission levels:

  • View Only can only view a project and not change any data.
  • Can Edit can create, modify, and delete annotations.
  • Can Transfer can upload and download media.
  • Can Execute can launch algorithm workflows.
  • Full Control can change project settings, including inviting new members, project name, and project metadata schema.
Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateMembership

Create membership.

Memberships specify a permission level of a user to a project. There are currently five cumulative permission levels:

  • View Only can only view a project and not change any data.
  • Can Edit can create, modify, and delete annotations.
  • Can Transfer can upload and download media.
  • Can Execute can launch algorithm workflows.
  • Full Control can change project settings, including inviting new members, project name, and project metadata schema.
Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
default_version
integer >= 1

Unique integer identifying a version.

permission
required
string
Enum: "View Only" "Can Edit" "Can Transfer" "Can Execute" "Full Control"

User permission level for the project.

user
required
integer >= 1

Unique integer identifying a user.

Responses

Request samples

Content type
application/json
{
  • "permission": "Full Control",
  • "user": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

MergeStates

Merges the source state into the target state. The target state will inherit the the source's localizations and will be deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying the target state to accept the merge.

Request Body schema: application/json
merge_state_id
required
integer

Unique integer identifying the state whose localizations will merge with this state.

Responses

Request samples

Content type
application/json
{
  • "merge_state_id": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Notify

Send a notification to administrators.

Uses the Slack API to send a notification to system administrators. This endpoint can only be used by system administrators and must be configured in a Tator deployment's settings.

Authorizations:
TokenAuthSessionAuth
Request Body schema: application/json
message
required
string

Message to send to administrators.

send_as_file
integer

Whether to send message as a file. (0 or 1)

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "send_as_file": 0
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

DeleteOrganization

Delete organization.

Organizations are used to represent groups of users. Multiple projects may be owned by an organization, and users may be members of multiple organizations.

Only organization owners may delete an organization.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetOrganization

Get organization.

Organizations are used to represent groups of users. Multiple projects may be owned by an organization, and users may be members of multiple organizations.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an organization.

Responses

Response samples

Content type
application/json
{
  • "default_membership_permission": "No Access",
  • "id": 0,
  • "name": "string",
  • "permission": "string",
  • "thumb": "string"
}

UpdateOrganization

Update organization.

Organizations are used to represent groups of users. Multiple projects may be owned by an organization, and users may be members of multiple organizations.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying an organization.

Request Body schema: application/json
default_membership_permission
string
Enum: "No Access" "View Only" "Can Edit" "Can Transfer" "Can Execute" "Full Control"

Default user permission level for all projects in this organization. If specified, users in this organizaiton will be automatically added to all projects in this organization with at least this permission level.

name
string

Name of the organization.

thumb
string

S3 key of thumbnail used to represent the organization.

Responses

Request samples

Content type
application/json
{
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetOrganizationUploadInfo

Retrieve URL for file upload to a given organization.

Authorizations:
TokenAuthSessionAuth
path Parameters
organization
required
integer

A unique integer identifying an organization.

query Parameters
expiration
integer [ 1 .. 86400 ]
Default: 86400

Number of seconds until URL expires and becomes invalid.

num_parts
integer [ 1 .. 10000 ]
Default: 1

Number of upload parts. Maximum part size is 5GB.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "upload_id": "string",
  • "urls": [
    ]
}

GetOrganizationList

Get organization list.

Organizations are used to represent groups of users. Multiple projects may be owned by an organization, and users may be members of multiple organizations.

Returns all organizations that a user is affiliated with.

Authorizations:
TokenAuthSessionAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateOrganization

Create organization.

Organizations are used to represent groups of users. Multiple projects may be owned by an organization, and users may be members of multiple organizations.

Authorizations:
TokenAuthSessionAuth
Request Body schema: application/json
default_membership_permission
string
Enum: "No Access" "View Only" "Can Edit" "Can Transfer" "Can Execute" "Full Control"

Default user permission level for all projects in this organization. If specified, users in this organizaiton will be automatically added to all projects in this organization with at least this permission level.

name
required
string

Name of the organization.

thumb
string

S3 key of thumbnail used to represent the organization.

Responses

Request samples

Content type
application/json
{
  • "name": "My Organization"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

CreatePasswordReset

Create password reset.

This endpoint will send an email to a registered user with the email address provided. The email will contain a link that will allow the user to reset their password. If the email address is registered for multiple users or no users an exception will be raised and an email will not be sent. If the email fails to be sent, either due to a bad response or system configuration that does not allow sending emails, an exception will be raised.

Authorizations:
TokenAuthSessionAuth
Request Body schema: application/json
email
required
string

Email address registered for user requesting reset.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

DeleteProject

Delete project.

Projects are the object under which all data in Tator is grouped, including user access, metadata definitions, media, and annotations. Data does not cross boundaries between projects.

Only project owners may delete a project. Note that deleting a project will also delete all media and annotations within a project.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetProject

Get project.

Projects are the object under which all data in Tator is grouped, including user access, metadata definitions, media, and annotations. Data does not cross boundaries between projects.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a project.

Responses

Response samples

Content type
application/json
{
  • "backup_bucket": 1,
  • "bucket": 1,
  • "created": "string",
  • "duration": 0,
  • "elemental_id": "string",
  • "enable_downloads": true,
  • "id": 0,
  • "name": "string",
  • "num_files": 0,
  • "organization": 1,
  • "permission": "string",
  • "size": 0,
  • "summary": "",
  • "thumb": "string",
  • "upload_bucket": 1,
  • "usernames": [
    ]
}

UpdateProject

Update project.

Projects are the object under which all data in Tator is grouped, including user access, metadata definitions, media, and annotations. Data does not cross boundaries between projects.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a project.

Request Body schema: application/json
backup_bucket
integer >= 1

Unique integer identifying a bucket for backups.

bucket
integer >= 1

Unique integer identifying a bucket.

elemental_id
string or null

The elemental ID of the object.

enable_downloads
boolean

Whether the UI should allow downloads for this project.

name
string

Name of the project.

summary
string

Summary of the project.

thumb
string

S3 key of thumbnail used to represent the project.

upload_bucket
integer >= 1

Unique integer identifying a bucket for uploads.

Responses

Request samples

Content type
application/json
{
  • "name": "New name",
  • "summary": "New summary"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetProjectList

Get project list.

Projects are the object under which all data in Tator is grouped, including user access, metadata definitions, media, and annotations. Data does not cross boundaries between projects.

Returns all projects that a user has access to.

Authorizations:
TokenAuthSessionAuth
query Parameters
organization
integer >= 1

Unique integer identifying an organization.

elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateProject

Create project.

Projects are the object under which all data in Tator is grouped, including user access, metadata definitions, media, and annotations. Data does not cross boundaries between projects.

Authorizations:
TokenAuthSessionAuth
query Parameters
organization
integer >= 1

Unique integer identifying an organization.

elemental_id
string

Elemental ID to search for

Request Body schema: application/json
backup_bucket
integer >= 1

Unique integer identifying a bucket for backups.

bucket
integer >= 1

Unique integer identifying a bucket.

elemental_id
string or null

The elemental ID of the object.

enable_downloads
boolean
Default: true

Whether the UI should allow downloads for this project.

name
required
string

Name of the project.

organization
required
integer >= 1

Unique integer identifying an organization.

summary
string
Default: ""

Summary of the project.

upload_bucket
integer >= 1

Unique integer identifying a bucket for uploads.

Responses

Request samples

Content type
application/json
{
  • "name": "My Project",
  • "summary": "First project"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

SaveAlgorithmManifest

Saves an uploaded algorithm manifest to the desired project. It is expected this manifest corresponds with an algorithm workflow to be registered by another endpoint.

Manifest is uploaded via tus, a separate mechanism from the REST API. Once a manifest upload is complete (a .yaml file), the file must be saved to the database using this endpoint.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project

Request Body schema: application/json
name
string

Name of manifest (.yaml) file

upload_url
string

URL of the uploaded file

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "upload_url": "string"
}

Response samples

Content type
application/json
{
  • "url": "string"
}

SaveGenericFile

Saves an uploaded non-media file to the desired project's permanent storage. It is expected that this file will be used in conjunction with an applet.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project

Request Body schema: application/json
name
string

Name of generic, non-media file

upload_url
string

URL of the uploaded file

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "upload_url": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "project": 0,
  • "upload_url": "string",
  • "url": "string"
}

DeleteSection

Delete section.

Sections represent groups of media using saved queries.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a section.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetSection

Get section.

Sections represent groups of media using saved queries.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a section.

Responses

Response samples

Content type
application/json
{
  • "elemental_id": "string",
  • "id": 0,
  • "name": "string",
  • "object_search": {
    },
  • "path": "string",
  • "project": 0,
  • "related_search": {
    },
  • "tator_user_sections": "string",
  • "visible": true
}

UpdateSection

Update section.

Sections represent groups of media using saved queries.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a section.

Request Body schema: application/json
elemental_id
string or null

The elemental ID of the object.

name
string

Unique name of the section.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
path
string or null

A path to represent nested sections. If not supplied, defaults to re.sub(r'[^A-Za-z0-9_-]',path)

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
tator_user_sections
string

Attribute that is applied to media to identify membership to a section.

visible
boolean

Determines the visibility in the UI.

Responses

Request samples

Content type
application/json
{
  • "elemental_id": "string",
  • "name": "string",
  • "object_search": {
    },
  • "path": "string",
  • "related_search": {
    },
  • "tator_user_sections": "string",
  • "visible": true
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

GetSectionList

Get section list.

Sections represent groups of media using saved queries.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
name
string

Name of the section.

elemental_id
string

Elemental ID to search for

match
string

Find any sections matching using an lquery. 

        - foo         Match the exact label path foo
        - *.foo.*     Match any label path containing the label foo
        - *.foo       Match any label path whose last label is foo

        Modifiers:
        - @           Match case-insensitively, for example a@ matches A
        - *           Match any label with this prefix, for example foo* matches foobar
        - %           Match initial underscore-separated words

        American@.Foot@*

        would match both
        america.Football and America.footwear
    
    For more information: https://www.postgresql.org/docs/current/ltree.html
ancestors
string

Find ancestors using using an lquery. 

        - foo         Match the exact label path foo
        - *.foo.*     Match any label path containing the label foo
        - *.foo       Match any label path whose last label is foo

        Modifiers:
        - @           Match case-insensitively, for example a@ matches A
        - *           Match any label with this prefix, for example foo* matches foobar
        - %           Match initial underscore-separated words

        American@.Foot@*

        would match both
        america.Football and America.footwear
    
    For more information: https://www.postgresql.org/docs/current/ltree.html
descendants
string

Find descendants using using an lquery. 

        - foo         Match the exact label path foo
        - *.foo.*     Match any label path containing the label foo
        - *.foo       Match any label path whose last label is foo

        Modifiers:
        - @           Match case-insensitively, for example a@ matches A
        - *           Match any label with this prefix, for example foo* matches foobar
        - %           Match initial underscore-separated words

        American@.Foot@*

        would match both
        america.Football and America.footwear
    
    For more information: https://www.postgresql.org/docs/current/ltree.html

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateSection

Create section.

Sections represent groups of media using saved queries.

Note: In order for a section to be interpreted properly, the tator_user_sections attribute of the SectionSpec cannot be None. The front end assigns a uuid1 string for this attribute, but it is not required to follow this pattern.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
elemental_id
string or null

The elemental ID of the object.

name
required
string

Unique name of the section.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
path
string or null

A path to represent nested sections. If not supplied, defaults to re.sub(r'[^A-Za-z0-9_-]',path)

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
tator_user_sections
string

Attribute that is applied to media to identify membership to a section.

visible
boolean

Determines the visibility in the UI.

Responses

Request samples

Content type
application/json
{
  • "elemental_id": "string",
  • "name": "string",
  • "object_search": {
    },
  • "path": "string",
  • "related_search": {
    },
  • "tator_user_sections": "string",
  • "visible": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteState

Delete state.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state.

Request Body schema: application/json
prune
integer [ 0 .. 1 ]
Default: 0

If set to 1 will purge the object from the database entirely. This removes any record, change-log, that this metadatum ever existed.

Responses

Request samples

Content type
application/json
{
  • "prune": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetState

Get state.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state.

Responses

Response samples

Content type
application/json
{
  • "attributes": {
    },
  • "created_by": 0,
  • "created_datetime": "2019-08-24T14:15:22Z",
  • "elemental_id": "string",
  • "frame": 0,
  • "id": 0,
  • "localizations": [
    ],
  • "media": [
    ],
  • "modified_by": 0,
  • "modified_datetime": "2019-08-24T14:15:22Z",
  • "parent": 0,
  • "segments": [
    ],
  • "type": 0,
  • "variant_deleted": true,
  • "version": 0
}

UpdateState

Update state.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state.

Request Body schema: application/json
object

Object containing attribute values.

elemental_id
string or null

The elemental ID of the object.

frame
integer

Frame number this state applies to.

localization_ids_add
Array of integers

List of new localization IDs that this state applies to.

localization_ids_remove
Array of integers

List of new localization IDs that this state applies to.

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

parent
number or null

If a clone, the pk of the parent.

reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

Responses

Request samples

Content type
application/json
{
  • "frame": 1001
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetStateCount

Get state list count.

This endpoint accepts the same query parameters as a GET or PUT request to the States endpoint, but only returns the number of states.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
0
0

GetStateCountById

Get state list count by ID.

This endpoint accepts the same query parameters as a GET or PUT request to the States endpoint, but only returns the number of states.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of state IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which states should be retrieved.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which states should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "object_search": {
    }
}

Response samples

Content type
application/json
0
0

GetStateGraphic

Get frame(s) of a given localization-associated state.

Use the mode argument to control whether it is an animated gif or a tiled jpg. A maximum of 100 detections may be retrieved at once. Use the length and offset parameters to control which section of a state is retrieved.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state.

query Parameters
mode
string
Default: "animate"
Enum: "animate" "tile"

Whether to animate or tile.

fps
number
Default: 2

Frame rate if mode is animate.

force_scale
string or null
Default: "224x224"
Example: force_scale=512x512

wxh to force each tile prior to stich

length
integer <= 100
Default: 100
Example: length=100

Number of detections to extract.

offset
integer
Default: 0
Example: offset=0

Index offset of detections to extract.

Responses

DeleteStateType

Delete state type.

A state type is the metadata definition object for a state. It includes association type, name, description, and may have any number of user-defined attribute types associated with it.

Note that this will also delete any states associated with the state type.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state type.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetStateType

Get state type.

A state type is the metadata definition object for a state. It includes association type, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state type.

Responses

Response samples

Content type
application/json
{
  • "association": "Media",
  • "attribute_types": [
    ],
  • "default_localization": 0,
  • "delete_child_localizations": false,
  • "description": "string",
  • "dtype": "string",
  • "elemental_id": "string",
  • "grouping_default": true,
  • "id": 0,
  • "interpolation": "none",
  • "media": [
    ],
  • "name": "string",
  • "project": 0,
  • "visible": true
}

UpdateStateType

Update state type.

A state type is the metadata definition object for a state. It includes association type, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a state type.

Request Body schema: application/json
delete_child_localizations
boolean

True if child localizations should be deleted when this state is deleted. Localizations will only be deleted if they are not associated with another state.

description
string

Description of the state type.

elemental_id
string or null

The elemental ID of the object.

grouping_default
boolean

Whether to group elements in the UI by default.

name
string

Name of the state type.

visible
boolean

Whether this state type should be displayed.

Responses

Request samples

Content type
application/json
{
  • "description": "New description",
  • "name": "New name"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetStateTypeList

Get state type list.

A state type is the metadata definition object for a state. It includes association type, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

List of unique integers identifying a media.

type
integer

Deprecated. Use LocalizationType endpoint to retrieve individual localization type by ID.

elemental_id
string

Elemental ID to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateStateType

Create state type.

A state type is the metadata definition object for a state. It includes association type, name, description, and may have any number of user-defined attribute types associated with it.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
association
required
string
Enum: "Media" "Frame" "Localization"

Type of object this state type is associated with.

Array of objects (AttributeType)

Attribute type definitions.

default_localization
integer

If this is a track type, this is a unique integer identifying the default localization type that is created when a track is created via the web interface.

delete_child_localizations
boolean
Default: false

True if child localizations should be deleted when this state is deleted. Localizations will only be deleted if they are not associated with another state.

description
string

Description of the state type.

elemental_id
string or null

The elemental ID of the object.

grouping_default
boolean
Default: true

Whether to group elements in the UI by default.

interpolation
string
Default: "latest"
Enum: "none" "latest" "attr_style_range"

Interpolation method used by the web interface.

media_types
required
Array of integers non-empty [ items >= 1 ]

List of integers identifying media types that this state type may apply to.

name
required
string

Name of the state type.

visible
boolean

Whether this state type should be displayed.

Responses

Request samples

Content type
application/json
{
  • "association": "Frame",
  • "attribute_types": [
    ],
  • "media_types": [
    ],
  • "name": "My state type"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteStateList

Delete state list.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

This method performs a bulk delete on all states matching a query. It is recommended to use a GET request first to check what is being deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of state IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which states should be retrieved.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which states should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
prune
integer [ 0 .. 1 ]
Default: 0

If set to 1 will purge the object from the database entirely. This removes any record, change-log, that this metadatum ever existed.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "object_search": {
    },
  • "prune": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetStateList

Get state list.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
[
  • {
    }
]

UpdateStateList

Update state list.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

This method does a bulk update on all states matching a query. Only user-defined attributes may be bulk updated.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
object

Attribute values to bulk update an entity list.

Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of state IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which states should be retrieved.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which states should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

new_elemental_id
string

The new elemental ID for these objects

new_version
integer

Unique integer identifying a new version for these objects

null_attributes
Array of strings[ items >= 1 ]

Null a value in the attributes body

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
reset_attributes
Array of strings[ items >= 1 ]

Reset an attribute to the default value specified in the Type object

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

Responses

Request samples

Content type
application/json
{
  • "attributes": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CreateStateList

Create state list.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

This method does a bulk create on a list of :class:tator.models.StateSpec objects; it also accepts a single instance. A maximum of 500 states may be created in one request.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
One of
<= 500 items
Array (<= 500 items)
object

Object containing attribute values.

elemental_id
string or null

The elemental ID of the object.

frame
integer

Frame number this state applies to.

localization_ids
Array of integers

List of localization IDs that this state applies to.

media_ids
required
Array of integers

List of media IDs that this state applies to.

parent
number or null

If a clone, the pk of the parent.

type
required
integer

Unique integer identifying a state type.

user_elemental_id
string

Unique ID of the original user who created this. If permissions allow, will change the creating user to the one referenced by this elemental_id

version
integer

Unique integer identifying the version.

Responses

Request samples

Content type
application/json
Example
{
  • "My First Attribute": "value1",
  • "My Second Attribute": "value2",
  • "frame": 1000,
  • "media_ids": [
    ],
  • "type": 1
}

Response samples

Content type
application/json
{
  • "id": [
    ],
  • "message": "string",
  • "object": [
    ]
}

GetStateListById

Get state list by ID.

A state is a description of a collection of other objects. The objects a state describes could be media (image or video), video frames, or localizations. A state referring to a collection of localizations is often referred to as a track. States are a type of entity in Tator, meaning they can be described by user defined attributes.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers

Comma-separated list of media IDs.

related_id
Array of integers

Comma-separated list of related IDs. If querying States, one can supply a list of related localization ids to filter on.If querying Localizations, one can supply a list of related state ids to filter on.

section
integer

Unique integer identifying a media section.

type
integer

Unique integer identifying a annotation type.

version
Array of integers

List of integers representing versions to fetch

after
integer

If given, all results returned will be after the localization with this ID. The start and stop parameters are relative to this modified range.

elemental_id
string

Elemental ID to search for

merge
integer [ 0 .. 1 ]
Default: 1

Reduce result set based on a server side merge. If multiple versions are selected and a variant of the object exists in both versions, the merge logic will return 1 or 0 objects. Example: Version B derives off Version A. An object, with the same elemental id "foo" exists on both. If Version B over A is selected and merge is turned on: + The "foo" present on Version B is returned + If the "foo" on version B is deleted, no "foo" is returned.

show_deleted
integer [ 0 .. 1 ]
Default: 0

Include in the return set objects that have variant_deleted set to True.

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of state IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which states should be retrieved.

media_ids
Array of integers[ items >= 1 ]

Array of parent media IDs for which states should be retrieved.

media_query
string

Query string used to filter media IDs. This can be used to avoid serialization and download of a media ID list.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "media_ids": [
    ],
  • "media_query": "string",
  • "object_search": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

DeleteTemporaryFile

Delete temporary file.

Temporary files are files stored server side for a defined duration.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a temporary file.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetTemporaryFile

Get temporary file.

Temporary files are files stored server side for a defined duration.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a temporary file.

Responses

Response samples

Content type
application/json
{
  • "created_datetime": "string",
  • "eol_datetime": "string",
  • "id": 0,
  • "lookup": "string",
  • "name": "string",
  • "path": "string",
  • "project": 0,
  • "user": 0
}

DeleteTemporaryFileList

Delete temporary file list.

Temporary files are files stored server side for a defined duration.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
expired
integer
Default: 0

If greater than 0 will return only expired files

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

GetTemporaryFileList

Get temporary file list.

Temporary files are files stored server side for a defined duration.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
expired
integer
Default: 0

If greater than 0 will return only expired files

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateTemporaryFile

Create temporary file.

Temporary files are files stored server side for a defined duration.

The file must first be uploaded via tus, and can subsequently be saved using this endpoint.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
hours
integer [ 1 .. 24 ]
Default: 24

Number of hours file is to be kept alive

lookup
required
string

md5hash of lookup parameters

name
required
string

Unique name for the temporary file

url
required
string

URL for the temporary file

Responses

Request samples

Content type
application/json
{
  • "hours": 24,
  • "lookup": "string",
  • "name": "string",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

CreateObtainAuthToken

Get API token.

This method accepts login credentials and returns an API token that can be used with the Tator REST API, tator-py, or tator-r.

Authorizations:
TokenAuthSessionAuth
Request Body schema: application/json
password
required
string

Account password.

refresh
boolean

If true, forces generation of new token.

username
required
string

Account username.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "refresh": true,
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

DeleteTranscode

Delete transcode job.

This method allows the user to cancel a transcode using the uid returned by Transcode create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
uid
required
string

A uuid1 string identifying to single Job.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetTranscode

Get transcode job.

This method allows the user to get a transcode's status using the uid returned by Transcode create method.

Authorizations:
TokenAuthSessionAuth
path Parameters
uid
required
string

A uuid1 string identifying to single Job.

Responses

Response samples

Content type
application/json
{
  • "job": {
    },
  • "spec": {
    }
}

DeleteTranscodeList

Delete transcode list.

This method performs a bulk delete on all transcodes matching a query. It is recommended to use a GET request first to check what is being deleted.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetTranscodeList

Get transcode list.

Get a list of active transcodes. This method accepts parameters that filter on Media in which case only transcodes on the filtered media list will be returned.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transcode

Start a transcode.

Videos in Tator must be transcoded to a multi-resolution streaming format before they can be viewed or annotated. This endpoint launches a transcode on raw uploaded video by creating an Argo workflow. The workflow will download the uploaded raw video, transcode it to the proper format, upload the transcoded video, and save the video using the VideoFile, AudioFile, and ImageFile endpoints. The transcode can be launched on an existing media object, or a media object will be created.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
attributes
object or null

Attributes to apply upon upload

object or null

Send an email message to members of the project using the Tator configured AWS email service

gid
required
string <uuid>

UUID generated for the job group. This value may be associated with messages generated during upload via the Progress endpoint, or it may be newly generated. The transcode workflow will use this value to generate progress messages.

md5
string

MD5 sum of the media file.

media_id
integer or null

ID of an existing media. If given, this media will be used for the transcode operation rather than creating a new object.

name
required
string

Name of the file.

section
required
string

Media section name to upload to.

size
integer >= 0

Size of the file in bytes. This parameter is required if the supplied URL is external (not produced by DownloadInfo and cannot accept HEAD requests.

type
required
integer

Unique integer identifying a video type.

uid
required
string

UUID generated for the individual job. This value may be associated with messages generated during upload via the Progress endpoint, or it may be newly generated. The transcode workflow will use this value to generate progress messages.

url
required
string

Upload URL for the raw video.

Responses

Request samples

Content type
application/json
{
  • "attributes": { },
  • "email_spec": {
    },
  • "gid": "02be4353-7111-4f22-ba28-5d5c245d174c",
  • "md5": "string",
  • "media_id": 0,
  • "name": "string",
  • "section": "string",
  • "size": 0,
  • "type": 0,
  • "uid": "string",
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

GetTranscodeListById

Get transcode list by ID.

Get a list of active transcodes. This method accepts parameters that filter on Media in which case only transcodes on the filtered media list will be returned. This method allows a request body containing additional query parameters.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
Array of integers[ items >= 1 ]

List of integers identifying media.

type
integer

Unique integer identifying media type.

name
string

Name of the media to filter on.

section
integer

Unique integer identifying a media section.

dtype
string
Enum: "image" "video" "multi"

Data type of the files, either image or video.

md5
string

MD5 sum of the media file.

gid
string

Upload group ID of the media file.

uid
string

Upload unique ID of the media file.

after
integer

If given, all results returned will be after the media with this ID. The start and stop parameters are relative to this modified range.

after_name
string

If given, all results returned will be after the media with this name. The start and stop parameters are relative to this modified range.

archive_lifecycle
string
Enum: "live" "archived" "all"

Archive lifecycle of the files, one of live (live only), archived (to_archive, archived, or to_live), or all. Defaults to 'live'

elemental_id
string

Elemental ID to search for

attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].

attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].

attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].

attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].

attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].

attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].

attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.

start
integer

Pagination start index. Index of the first item in a larger list to return.

stop
integer

Pagination stop index. Non-inclusive index of the last item in a larger list to return.

encoded_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec

sort_by
Array of strings

Field names to sort results by. Built-in names should be prefixed with '$', attributes must not be. 

    Because the schema supports sorting by a list of attributes (effectively grouping), we have to utilize a special character to inform direction.
    Uses the common convention of '-'; thus `["$name", "-$id"]` would sort by name ascending and break tie-breakers(grouping) by descending by id.

    An example REST query will sort all localizations in project 1, by label descending and sort any ties by ascending x.

    `rest/Localizations/1?sort_by=-Label&sort_by=$x`


    A table of built-ins available for a given type:
                
| Name              | Description                            | Localizations | States | Medias | Leaves | Files | 
|-------------------|----------------------------------------|---------------|--------|--------|--------|-------|
| section           | Media section                          |       X       |   X    |   X    |        |       |
| created_datetime  | The time of creation for this datum    |       X       |   X    |   X    |    X   |   X   |
| created_by        | The user id who created this datum     |       X       |   X    |   X    |    X   |   X   |
| modified_datetime | The last modification time             |       X       |   X    |   X    |    X   |   X   |
| modified_by       | The last modification user             |       X       |   X    |   X    |    X   |   X   |
| name              | The name of the element                |               |        |   X    |    X   |   X   |
| fps               | The frames per second                  |               |        |   X    |        |       |
| deleted           | Whether the media is marked deleted    |               |        |   X    |    X   |   X   |
| variant_deleted   | Whether the metadata is marked deleted |       X       |   X    |        |        |       |
| archive_state     | The current archive state of the media |               |        |   X    |        |       |
| x, y, u, or v     | Geometric coordinates                  |               |        |        |        |       |
| width or height   | Geometric sizes                        |               |        |        |        |       |
| incident          | Available when doing a related search  |               |        |   X    |        |       |
related_attribute
Array of strings

Attribute equality filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lt
Array of strings

Attribute less than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_lte
Array of strings

Attribute less than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gt
Array of strings

Attribute greater than filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_gte
Array of strings

Attribute greater than or equal filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_contains
Array of strings

Attribute contains filter. Format is attribute1::value1,[attribute2::value2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_distance
Array of strings

Range filter for geoposition attributes. Format is attribute1::distance_km2::lat2::lon2,[attribute2::distancekm2::lat2::lon2].This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

related_attribute_null
Array of strings

Attribute null filter. Returns elements for which a given attribute is not defined.This filter is applied to related data of the primary object.On the Media endpoint, this searches on related metadata(States/Localizations).On metadata endpoints, this searches on related media.

encoded_related_search
string

Base64 encoded string representing an Object_Search defined in /components/AttributeOperationSpec applied against related objects

Request Body schema: application/json
Array of objects (FloatArrayQuery)

Searches on float_array attributes.

ids
Array of integers[ items >= 1 ]

Array of media IDs to retrieve.

localization_ids
Array of integers[ items >= 1 ]

Array of child localization IDs for which media should be retrieved.

AttributeCombinatorSpec (object) or AttributeFilterSpec (object) (AttributeOperationSpec)

Operation(s) to apply to attribute(s) for a complex filter

Basic:

# Matches Freddie Mercury or Fred Thompson
{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred'}

Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "name LIKE Fred% OR name LIKE Robert%"
{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}

Nested Combination

# Matches "Freddie Mercury or "Fred Thompson" or "Robert Redford". SQL Looks like "age >= 30 AND (name LIKE Fred% OR name LIKE Robert%)"
{'method': 'AND', 'operations': [{'method':'OR', 'operations': [{'attribute': 'name', 'operation': 'icontains', 'value': 'Fred' },{'attribute': 'name', 'operation': 'icontains', 'value': 'Robert' }]}, {'attribute': 'age', 'operation': 'gte', 'value': 30 }]}
state_ids
Array of integers[ items >= 1 ]

Array of child state IDs for which media should be retrieved.

Responses

Request samples

Content type
application/json
{
  • "float_array": [
    ],
  • "ids": [
    ],
  • "localization_ids": [
    ],
  • "object_search": {
    },
  • "state_ids": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

TrimStateEnd

Trims the state's start or end point by deleting the localizations before the new start point or after the new end point.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying the state to trim

Request Body schema: application/json
endpoint
required
string
Enum: "start" "end"

End point to trim to using the provided frame number.

frame
required
integer >= 0

Frame number of new end point

Responses

Request samples

Content type
application/json
{
  • "endpoint": "start",
  • "frame": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

CompleteUpload

Complete multipart upload.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
key
string

An object key that can be supplied to the Transcode or Media endpoint after the file has been uploaded.

Array of objects (UploadPart) [ 2 .. 10000 ] items

List of objects containing part number for each PUT request and ETag header from each response.

upload_id
string

An upload ID.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "parts": [
    ],
  • "upload_id": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetUploadInfo

Retrieve URL for file upload to a given project.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
expiration
integer [ 1 .. 86400 ]
Default: 86400

Number of seconds until URL expires and becomes invalid.

num_parts
integer [ 1 .. 10000 ]
Default: 1

Number of upload parts. Maximum part size is 5GB.

media_id
integer >= 1

Media ID if this is an upload for existing media.

file_id
integer >= 1

File ID if this is an upload for existing file.

filename
string

Filename to use if media_id is given. If a file with the same name already exists under the given media ID prefix, the new upload will replace it. Ignored if media_id is not given.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "upload_id": "string",
  • "urls": [
    ]
}

UserExists

Returns whether a user exists.

Authorizations:
TokenAuthSessionAuth
query Parameters
username
string

Username associated with user. Either this or email must be supplied.

email
string

Email address associated with user. Either this or email must be supplied.

elemental_id
string

Elemental_id of user

Responses

Response samples

Content type
application/json
true

Whoami

Get current user.

Retrieves user making the request.

Authorizations:
TokenAuthSessionAuth
query Parameters
presigned
integer [ 1 .. 86400 ]

If given, all object key fields in profile will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

Responses

Response samples

Content type
application/json
{
  • "elemental_id": "string",
  • "email": "string",
  • "first_name": "string",
  • "id": 0,
  • "is_staff": true,
  • "last_name": "string",
  • "profile": { },
  • "username": "string"
}

GetUser

Get user.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a user.

query Parameters
presigned
integer [ 1 .. 86400 ]

If given, all object key fields in profile will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

Responses

Response samples

Content type
application/json
{
  • "elemental_id": "string",
  • "email": "string",
  • "first_name": "string",
  • "id": 0,
  • "is_staff": true,
  • "last_name": "string",
  • "profile": { },
  • "username": "string"
}

UpdateUser

Update user.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a user.

query Parameters
presigned
integer [ 1 .. 86400 ]

If given, all object key fields in profile will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

Request Body schema: application/json
clear_avatar
integer
Default: 0

Set to >0 to clear the current avatar of the user

clear_profile_keys
Array of strings

Clear the given keys from the profile dictionary

elemental_id
string

Unique ID for a user across clusters/deployments

email
string

Email address of user.

first_name
string

First name of user.

last_name
string

Last name of user.

new_avatar
string

b64 encoded image to use for the avatar of the user.This file is verified to meet system constraints: - Less than 1Mb - a mimetype of image/png or image/jpg

password
string

Account password.

reset_token
string

Password reset token generated by PasswordReset object.

set_profile_keys
object

Key/Value Pairs to set atomically

Responses

Request samples

Content type
application/json
{
  • "clear_avatar": 0,
  • "clear_profile_keys": [
    ],
  • "elemental_id": "string",
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "new_avatar": "string",
  • "password": "string",
  • "reset_token": "string",
  • "set_profile_keys": { }
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

GetUserList

Get list of users.

Authorizations:
TokenAuthSessionAuth
query Parameters
username
string

Username associated with user. Either this or email must be supplied.

email
string

Email address associated with user. Either this or email must be supplied.

elemental_id
string

Elemental_id of user

presigned
integer [ 1 .. 86400 ]

If given, all object key fields in profile will be replaced with presigned URLs that can be downloaded without authentication. The value is the expiration time of the URLs in seconds.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateUser

Create user.

This method accepts a registration token that is provided by creating a Invitation object. It is optional if anonymous registration is enabled, but otherwise required. If anonymous registration is enabled and email confirmation is also enabled, the method will create an inactive user with a confirmation token. The user can be activated by visiting a link that is automatically sent to the user. If anonymous registration without confirmation is enabled, any user can be created with this method.

Authorizations:
TokenAuthSessionAuth
Request Body schema: application/json
elemental_id
string

Unique ID for a user across clusters/deployments

email
required
string

Email address of user.

first_name
required
string

First name of user.

last_name
required
string

Last name of user.

new_avatar
string

b64 encoded image to use for the avatar of the user

password
required
string

Account password.

profile
object

User profile information

registration_token
string

Registration token generated by Invitation object.

username
required
string

Username of user.

Responses

Request samples

Content type
application/json
{
  • "elemental_id": "string",
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "new_avatar": "string",
  • "password": "string",
  • "profile": { },
  • "registration_token": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "details": "string",
  • "message": "string"
}

DeleteVersion

Delete version.

Versions allow for multiple "layers" of annotations on the same media. Versions are created at the project level, but are only displayed for a given media if that media contains annotations in that version. The version of an annotation can be set by providing it in a POST operation. Currently only localizations and states can have versions.

Note that this will also delete any localizations or states associated with the deleted version.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a version.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetVersion

Get version.

Versions allow for multiple "layers" of annotations on the same media. Versions are created at the project level, but are only displayed for a given media if that media contains annotations in that version. The version of an annotation can be set by providing it in a POST operation. Currently only localizations and states can have versions.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a version.

Responses

Response samples

Content type
application/json
{
  • "bases": [
    ],
  • "created_by": "string",
  • "description": "",
  • "elemental_id": "string",
  • "id": 0,
  • "name": "string",
  • "number": 0,
  • "project": 0,
  • "show_empty": true
}

UpdateVersion

Update version.

Versions allow for multiple "layers" of annotations on the same media. Versions are created at the project level, but are only displayed for a given media if that media contains annotations in that version. The version of an annotation can be set by providing it in a POST operation. Currently only localizations and states can have versions.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a version.

Request Body schema: application/json
bases
Array of integers >= 0

Array of other version IDs that are dependencies of this version.

description
string
Default: ""

Description of the version.

elemental_id
string

Unique ID of an element

name
string

Name of the version.

show_empty
boolean
Default: true

Whether to show this version on media for which no annotations exist.

Responses

Request samples

Content type
application/json
{
  • "bases": [
    ],
  • "description": "New description",
  • "name": "New name",
  • "show_empty": true
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetVersionList

Get version list.

Versions allow for multiple "layers" of annotations on the same media. Versions are created at the project level, but are only displayed for a given media if that media contains annotations in that version. The version of an annotation can be set by providing it in a POST operation. Currently only localizations and states can have versions.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

query Parameters
media_id
integer

Unique integer identifying a media.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateVersion

Create version.

Versions allow for multiple "layers" of annotations on the same media. Versions are created at the project level, but are only displayed for a given media if that media contains annotations in that version. The version of an annotation can be set by providing it in a POST operation. Currently only localizations and states can have versions.

Authorizations:
TokenAuthSessionAuth
path Parameters
project
required
integer

A unique integer identifying a project.

Request Body schema: application/json
bases
Array of integers >= 0

Array of other version IDs that are dependencies of this version.

description
string
Default: ""

Description of the version.

elemental_id
string

Unique ID of an element

name
required
string

Name of the version.

show_empty
boolean
Default: true

Whether to show this version on media for which no annotations exist.

Responses

Request samples

Content type
application/json
{
  • "bases": [
    ],
  • "description": "New description",
  • "name": "My new version",
  • "show_empty": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "message": "string",
  • "object": { }
}

DeleteVideoFile

Delete video file.

Video files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying video. One or more video files can be used to reference streaming or archival roles in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the video file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "streaming" "archival"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of videos for the specified role.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

GetVideoFile

Get video file.

Video files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying video. One or more video files can be used to reference streaming or archival roles in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the video file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "streaming" "archival"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of videos for the specified role.

Responses

Response samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "reference_only": 0,
  • "resolution": [
    ],
  • "segment_info": "string",
  • "size": 0
}

UpdateVideoFile

Update video file.

Video files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying video. One or more video files can be used to reference streaming or archival roles in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the video file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "streaming" "archival"

Role of media file being referenced.

index
required
integer >= 0

Index of object. Must be less than size of current list of videos for the specified role.

Request Body schema: application/json
bit_rate
integer

Bit rate in bits per second

codec
required
string

Human readable codec.

codec_description
string

Description other than codec.

codec_mime
string

Example mime: "video/mp4; codecs="avc1.64001e"". Only relevant for streaming files, will assume example above if not present.

host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

path
required
string

Relative URL to the file.

reference_only
integer <= 1
Default: 0

Do not import the media resources into Tator. This causes the resources to be accessed at the supplied URL upon access in the UI.

resolution
required
Array of integers = 2 items [ items >= 1 ]

Resolution of the video in pixels (height, width).

segment_info
string

Path to json file containing segment info. Required if media role is streaming.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "reference_only": 0,
  • "resolution": [
    ],
  • "segment_info": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}

GetVideoFileList

Get video file list.

Video files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying video. One or more video files can be used to reference streaming or archival roles in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the video file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "streaming" "archival"

Role of media file being referenced.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

CreateVideoFile

Create video file.

Video files are stored under the media_files field of Media objects. They are used to relate media metadata to an underlying video. One or more video files can be used to reference streaming or archival roles in a Media object. The file itself must first be uploaded to a URL retrieved from the UploadInfo endpoint, and the returned object key should be specified in the video file's path field.

Authorizations:
TokenAuthSessionAuth
path Parameters
id
required
integer

A unique integer identifying a media object.

query Parameters
role
required
string
Enum: "streaming" "archival"

Role of media file being referenced.

index
integer >= 0

Insertion index. Must be less than size of current list of videos for the specified role. If omitted, the video file will be appended to the end of the list.

Request Body schema: application/json
bit_rate
integer

Bit rate in bits per second

codec
required
string

Human readable codec.

codec_description
string

Description other than codec.

codec_mime
string

Example mime: "video/mp4; codecs="avc1.64001e"". Only relevant for streaming files, will assume example above if not present.

host
string

If supplied will use this instead of currently connected host, e.g. https://example.com

http_auth
string

If specified will be used for HTTP authorization in request for media, i.e. "bearer TOKEN".

path
required
string

Relative URL to the file.

reference_only
integer <= 1
Default: 0

Do not import the media resources into Tator. This causes the resources to be accessed at the supplied URL upon access in the UI.

resolution
required
Array of integers = 2 items [ items >= 1 ]

Resolution of the video in pixels (height, width).

segment_info
string

Path to json file containing segment info. Required if media role is streaming.

size
integer

File size in bytes.

Responses

Request samples

Content type
application/json
{
  • "bit_rate": 0,
  • "codec": "string",
  • "codec_description": "string",
  • "codec_mime": "string",
  • "host": "string",
  • "http_auth": "string",
  • "path": "string",
  • "reference_only": 0,
  • "resolution": [
    ],
  • "segment_info": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "message": "string"
}