_description: "Provides a management API for tasks in the system."
_references {
status_change_request {
type: object
properties {
task {
description: Task ID
type: string
}
status_reason {
description: Reason for status change
type: string
}
status_message {
description: Extra information regarding status change
type: string
}
}
}
// "force" field with default description
force_arg {
type: boolean
default: false
description: "Allows forcing state change even if transition is not supported"
}
}
_definitions {
include "_common.conf"
multi_field_pattern_data {
type: object
properties {
pattern {
description: "Pattern string (regex)"
type: string
}
fields {
description: "List of field names"
type: array
items { type: string }
}
}
}
script {
type: object
properties {
binary {
description: "Binary to use when running the script"
type: string
default: python
}
repository {
description: "Name of the repository where the script is located"
type: string
}
tag {
description: "Repository tag"
type: string
}
branch {
description: "Repository branch id If not provided and tag not provided, default repository branch is used."
type: string
}
version_num {
description: "Version (changeset) number. Optional (default is head version) Unused if tag is provided."
type: string
}
entry_point {
description: "Path to execute within the repository"
type: string
}
working_dir {
description: "Path to the folder from which to run the script Default - root folder of repository"
type: string
}
requirements {
description: "A JSON object containing requirements strings by key"
type: object
}
diff {
description: "Uncommitted changes found in the repository when task was run"
type: string
}
}
}
output {
type: object
properties {
destination {
description: "Storage id. This is where output files will be stored."
type: string
}
model {
description: "Model id."
type: string
}
result {
description: "Task result. Values: 'success', 'failure'"
type: string
}
error {
description: "Last error text"
type: string
}
}
}
task_execution_progress_enum {
type: string
enum: [
unknown
running
stopping
stopped
]
}
output_rois_enum {
type: string
enum: [
all_in_frame
only_filtered
frame_per_roi
]
}
artifact_type_data {
type: object
properties {
preview {
description: "Description or textual data"
type: string
}
content_type {
description: "System defined raw data content type"
type: string
}
data_hash {
description: "Hash of raw data, without any headers or descriptive parts"
type: string
}
}
}
artifact {
type: object
required: [key, type]
properties {
key {
description: "Entry key"
type: string
}
type {
description: "System defined type"
type: string
}
mode {
description: "System defined input/output indication"
type: string
enum: [
input
output
]
default: output
}
uri {
description: "Raw data location"
type: string
}
content_size {
description: "Raw data length in bytes"
type: integer
}
hash {
description: "Hash of entire raw data"
type: string
}
timestamp {
description: "Epoch time when artifact was created"
type: integer
}
type_data {
description: "Additional fields defined by the system"
"$ref": "#/definitions/artifact_type_data"
}
display_data {
description: "User-defined list of key/value pairs, sorted"
type: array
items {
type: array
items {
type: string # can also be a number... TODO: upgrade the generator
}
}
}
}
}
execution {
type: object
properties {
queue {
description: "Queue ID where task was queued."
type: string
}
parameters {
description: "Json object containing the Task parameters"
type: object
additionalProperties: true
}
model {
description: "Execution input model ID Not applicable for Register (Import) tasks"
type: string
}
model_desc {
description: "Json object representing the Model descriptors"
type: object
additionalProperties: true
}
model_labels {
description: """Json object representing the ids of the labels in the model.
The keys are the layers' names and the values are the IDs.
Not applicable for Register (Import) tasks.
Mandatory for Training tasks"""
type: object
additionalProperties: { type: integer }
}
framework {
description: """Framework related to the task. Case insensitive. Mandatory for Training tasks. """
type: string
}
docker_cmd {
description: "Command for running docker script for the execution of the task"
type: string
}
artifacts {
description: "Task artifacts"
type: array
items { "$ref": "#/definitions/artifact" }
}
}
}
task_status_enum {
type: string
enum: [
created
queued
in_progress
stopped
published
publishing
closed
failed
completed
unknown
]
}
task_type_enum {
type: string
enum: [
training
testing
inference
data_processing
application
monitor
controller
optimizer
service
qc
custom
]
}
last_metrics_event {
type: object
properties {
metric {
description: "Metric name"
type: string
}
variant {
description: "Variant name"
type: string
}
value {
description: "Last value reported"
type: number
}
min_value {
description: "Minimum value reported"
type: number
}
max_value {
description: "Maximum value reported"
type: number
}
}
}
last_metrics_variants {
type: object
description: "Last metric events, one for each variant hash"
additionalProperties {
"$ref": "#/definitions/last_metrics_event"
}
}
task {
type: object
properties {
id {
description: "Task id"
type: string
}
name {
description: "Task Name"
type: string
}
user {
description: "Associated user id"
type: string
}
company {
description: "Company ID"
type: string
}
type {
description: "Type of task. Values: 'training', 'testing'"
"$ref": "#/definitions/task_type_enum"
}
status {
description: ""
"$ref": "#/definitions/task_status_enum"
}
comment {
description: "Free text comment"
type: string
}
created {
description: "Task creation time (UTC) "
type: string
format: "date-time"
}
started {
description: "Task start time (UTC)"
type: string
format: "date-time"
}
completed {
description: "Task end time (UTC)"
type: string
format: "date-time"
}
parent {
description: "Parent task id"
type: string
}
project {
description: "Project ID of the project to which this task is assigned"
type: string
}
output {
description: "Task output params"
"$ref": "#/definitions/output"
}
execution {
description: "Task execution params"
"$ref": "#/definitions/execution"
}
// TODO: will be removed
script {
description: "Script info"
"$ref": "#/definitions/script"
}
tags {
description: "User-defined tags list"
type: array
items { type: string }
}
system_tags {
description: "System tags list. This field is reserved for system use, please don't use it."
type: array
items { type: string }
}
status_changed {
description: "Last status change time"
type: string
format: "date-time"
}
status_message {
description: "free text string representing info about the status"
type: string
}
status_reason {
description: "Reason for last status change"
type: string
}
published {
description: "Last status change time"
type: string
format: "date-time"
}
last_worker {
description: "ID of last worker that handled the task"
type: string
}
last_worker_report {
description: "Last time a worker reported while working on this task"
type: string
format: "date-time"
}
last_update {
description: "Last time this task was created, updated, changed or events for this task were reported"
type: string
format: "date-time"
}
last_iteration {
description: "Last iteration reported for this task"
type: integer
}
last_metrics {
description: "Last metric variants (hash to events), one for each metric hash"
type: object
additionalProperties {
"$ref": "#/definitions/last_metrics_variants"
}
}
}
}
}
get_by_id {
"2.1" {
description: "Gets task information"
request {
type: object
required: [ task ]
properties {
task {
description: "Task ID"
type: string
}
}
}
response {
type: object
properties {
task {
description: "Task info"
"$ref": "#/definitions/task"
}
}
}
}
}
get_all_ex {
internal: true
"2.1": ${get_all."2.1"}
}
get_all {
"2.1" {
description: "Get all the company's tasks and all public tasks"
request {
type: object
properties {
id {
description: "List of IDs to filter by"
type: array
items { type: string }
}
name {
description: "Get only tasks whose name matches this pattern (python regular expression syntax)"
type: string
}
user {
description: "List of user IDs used to filter results by the task's creating user"
type: array
items { type: string }
}
project {
type: array
items { type: string }
}
page {
description: "Page number, returns a specific page out of the resulting list of tasks"
type: integer
minimum: 0
}
page_size {
description: "Page size, specifies the number of results returned in each page (last page may contain fewer results)"
type: integer
minimum: 1
}
order_by {
description: """List of field names to order by. When search_text is used,
'@text_score' can be used as a field representing the text score of returned documents.
Use '-' prefix to specify descending order. Optional, recommended when using page.
If the first order field is a hyper parameter or metric then string values are ordered
according to numeric ordering rules where applicable"""
type: array
items { type: string }
}
type {
description: "List of task types. One or more of: 'import', 'annotation', 'training' or 'testing' (case insensitive)"
type: array
items { type: string }
}
tags {
description: "List of task user-defined tags. Use '-' prefix to exclude tags"
type: array
items { type: string }
}
system_tags {
description: "List of task system tags. Use '-' prefix to exclude system tags"
type: array
items { type: string }
}
status {
description: "List of task status."
type: array
items { "$ref": "#/definitions/task_status_enum" }
}
project {
description: "List of project IDs"
type: array
items { type: string }
}
only_fields {
description: "List of task field names (nesting is supported using '.', e.g. execution.model_labels). If provided, this list defines the query's projection (only these fields will be returned for each result entry)"
type: array
items { type: string }
}
parent {
description: "Parent ID"
type: string
}
status_changed {
description: "List of status changed constraint strings (utcformat, epoch) with an optional prefix modifier (>, >=, <, <=)"
type: array
items {
type: string
pattern: "^(>=|>|<=|<)?.*$"
}
}
search_text {
description: "Free text search query"
type: string
}
_all_ {
description: "Multi-field pattern condition (all fields match pattern)"
"$ref": "#/definitions/multi_field_pattern_data"
}
_any_ {
description: "Multi-field pattern condition (any field matches pattern)"
"$ref": "#/definitions/multi_field_pattern_data"
}
}
dependencies {
page: [ page_size ]
}
}
response {
type: object
properties {
tasks {
description: "List of tasks"
type: array
items { "$ref": "#/definitions/task" }
}
}
}
}
}
get_types {
"2.8" {
description: "Get the list of task types used in the specified projects"
request {
type: object
properties {
projects {
description: "The list of projects which tasks will be analyzed. If not passed or empty then all the company and public tasks will be analyzed"
type: array
items: {type: string}
}
}
}
response {
type: object
properties {
types {
description: "Unique list of the task types used in the requested projects"
type: array
items: {type: string}
}
}
}
}
}
clone {
"2.5" {
description: "Clone an existing task"
request {
type: object
required: [ task ]
properties {
task {
description: "ID of the task"
type: string
}
new_task_name {
description: "The name of the cloned task. If not provided then taken from the original task"
type: string
}
new_task_comment {
description: "The comment of the cloned task. If not provided then taken from the original task"
type: string
}
new_task_tags {
description: "The user-defined tags of the cloned task. If not provided then taken from the original task"
type: array
items { type: string }
}
new_task_system_tags {
description: "The system tags of the cloned task. If not provided then empty"
type: array
items { type: string }
}
new_task_parent {
description: "The parent of the cloned task. If not provided then taken from the original task"
type: string
}
new_task_project {
description: "The project of the cloned task. If not provided then taken from the original task"
type: string
}
execution_overrides {
description: "The execution params for the cloned task. The params not specified are taken from the original task"
"$ref": "#/definitions/execution"
}
validate_references {
description: "If set to 'false' then the task fields that are copied from the original task are not validated. The default is false."
type: boolean
}
}
}
response {
type: object
properties {
id {
description: "ID of the new task"
type: string
}
}
}
}
}
create {
"2.1" {
description: "Create a new task"
request {
type: object
required: [
name
type
]
properties {
name {
description: "Task name. Unique within the company."
type: string
}
tags {
description: "User-defined tags list"
type: array
items { type: string }
}
system_tags {
description: "System tags list. This field is reserved for system use, please don't use it."
type: array
items { type: string }
}
type {
description: "Type of task"
"$ref": "#/definitions/task_type_enum"
}
comment {
description: "Free text comment "
type: string
}
parent {
description: "Parent task id Must be a completed task."
type: string
}
project {
description: "Project ID of the project to which this task is assigned Must exist[ab]"
type: string
}
output_dest {
description: "Output storage id Must be a reference to an existing storage."
type: string
}
execution {
description: "Task execution params"
"$ref": "#/definitions/execution"
}
script {
description: "Script info"
"$ref": "#/definitions/script"
}
}
}
response {
type: object
properties {
id {
description: "ID of the task"
type: string
}
}
}
}
}
validate {
"2.1" {
description: "Validate task properties (before create)"
request {
type: object
required: [
name
type
]
properties {
name {
description: "Task name. Unique within the company."
type: string
}
tags {
description: "User-defined tags list"
type: array
items { type: string }
}
system_tags {
description: "System tags list. This field is reserved for system use, please don't use it."
type: array
items { type: string }
}
type {
description: "Type of task"
"$ref": "#/definitions/task_type_enum"
}
comment {
description: "Free text comment "
type: string
}
parent {
description: "Parent task id Must be a completed task."
type: string
}
project {
description: "Project ID of the project to which this task is assigned Must exist[ab]"
type: string
}
output_dest {
description: "Output storage id Must be a reference to an existing storage."
type: string
}
execution {
description: "Task execution params"
"$ref": "#/definitions/execution"
}
script {
description: "Script info"
"$ref": "#/definitions/script"
}
}
}
response {
type: object
additionalProperties: false
}
}
}
update {
"2.1" {
description: "Update task's runtime parameters"
request {
type: object
required: [
task
]
properties {
task {
description: "ID of the task"
type: string
}
name {
description: "Task name Unique within the company."
type: string
}
tags {
description: "User-defined tags list"
type: array
items { type: string }
}
system_tags {
description: "System tags list. This field is reserved for system use, please don't use it."
type: array
items { type: string }
}
comment {
description: "Free text comment "
type: string
}
project {
description: "Project ID of the project to which this task is assigned"
type: string
}
output__error {
description: "Free text error"
type: string
}
created {
description: "Task creation time (UTC) "
type: string
format: "date-time"
}
}
}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
update_batch {
"2.1" {
description: """Updates a batch of tasks.
Headers
Content type should be 'application/json-lines'."""
batch_request: {
action: update
version: 1.5
}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
}
}
}
}
edit {
"2.1" {
description: "Edit task's details."
request {
type: object
required: [
task
]
properties {
task {
description: "ID of the task"
type: string
}
force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not 'created'"
}
name {
description: "Task name Unique within the company."
type: string
}
tags {
description: "User-defined tags list"
type: array
items { type: string }
}
system_tags {
description: "System tags list. This field is reserved for system use, please don't use it."
type: array
items { type: string }
}
type {
description: "Type of task"
"$ref": "#/definitions/task_type_enum"
}
comment {
description: "Free text comment "
type: string
}
parent {
description: "Parent task id Must be a completed task."
type: string
}
project {
description: "Project ID of the project to which this task is assigned Must exist[ab]"
type: string
}
output_dest {
description: "Output storage id Must be a reference to an existing storage."
type: string
}
execution {
description: "Task execution params"
"$ref": "#/definitions/execution"
}
script {
description: "Script info"
"$ref": "#/definitions/script"
}
}
}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
reset {
"2.1" {
description: "Reset a task to its initial state, along with any information stored for it (statistics, frame updates etc.)."
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg} {
description: "If not true, call fails if the task status is 'completed'"
}
properties.clear_all {
description: "Clear script and execution sections completely"
type: boolean
default: false
}
} ${_references.status_change_request}
response {
type: object
properties {
deleted_indices {
description: "List of deleted ES indices that were removed as part of the reset process"
type: array
items { type: string }
}
dequeued {
description: "Response from queues.remove_task"
type: object
additionalProperties: true
}
frames {
description: "Response from frames.rollback"
type: object
additionalProperties: true
}
events {
description: "Response from events.delete_for_task"
type: object
additionalProperties: true
}
deleted_models {
description: "Number of output models deleted by the reset"
type: integer
}
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
delete {
"2.1" {
description: """Delete a task along with any information stored for it (statistics, frame updates etc.)
Unless Force flag is provided, operation will fail if task has objects associated with it - i.e. children tasks and projects.
Models that refer to the deleted task will be updated with a task ID indicating a deleted task.
"""
request = {
type: object
required: [
task
]
properties {
move_to_trash {
description: "Move task to trash instead of deleting it. For internal use only, tasks in the trash are not visible from the API and cannot be restored!"
type: boolean
default: false
}
force = ${_references.force_arg} {
description: "If not true, call fails if the task status is 'in_progress'"
}
}
} ${_references.status_change_request}
response {
type: object
properties {
deleted {
description: "Indicates whether the task was deleted"
type: boolean
}
updated_children {
description: "Number of child tasks whose parent property was updated"
type: integer
}
updated_models {
description: "Number of models whose task property was updated"
type: integer
}
updated_versions {
description: "Number of dataset versions whose task property was updated"
type: integer
}
frames {
description: "Response from frames.rollback"
type: object
additionalProperties: true
}
events {
description: "Response from events.delete_for_task"
type: object
additionalProperties: true
}
}
}
}
}
started {
"2.1" {
description: "Mark a task status as in_progress. Optionally allows to set the task's execution progress."
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not 'not_started'"
}
} ${_references.status_change_request}
response {
type: object
properties {
started {
description: "Number of tasks started (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
stop {
"2.1" {
description: "Request to stop a running task"
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not 'in_progress'"
}
} ${_references.status_change_request}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
stopped {
"2.1" {
description: "Signal a task has stopped"
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not 'stopped'"
}
} ${_references.status_change_request}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
failed {
"2.1" {
description: "Indicates that task has failed"
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg}
} ${_references.status_change_request}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
close {
"2.1" {
description: "Indicates that task is closed"
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg}
} ${_references.status_change_request}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
publish {
"2.1" {
description: """Mark a task status as published.
For Annotation tasks - if any changes were committed by this task, a new version in the dataset together with an output view are created.
For Training tasks - if a model was created, it should be set to ready."""
request = {
type: object
required: [
task
]
properties {
force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not 'stopped'"
}
publish_model {
description: "Indicates that the task output model (if exists) should be published. Optional, the default value is True."
type: boolean
}
}
} ${_references.status_change_request}
response {
type: object
properties {
committed_versions_results {
description: "Committed versions results"
type: array
items {
type: object
additionalProperties: true
}
}
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
enqueue {
"1.5" {
description: """Adds a task into a queue.
Fails if task state is not 'created'.
Fails if the following parameters in the task were not filled:
* execution.script.repository
* execution.script.entrypoint
"""
request = {
type: object
required: [
task
]
properties {
queue {
description: "Queue id. If not provided, task is added to the default queue."
type: string
}
}
} ${_references.status_change_request}
response {
type: object
properties {
queued {
description: "Number of tasks queued (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
dequeue {
"1.5" {
description: """Remove a task from its queue.
Fails if task status is not queued."""
request = {
type: object
required: [
task
]
} ${_references.status_change_request}
response {
type: object
properties {
dequeued {
description: "Number of tasks dequeued (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
set_requirements {
"2.1" {
description: """Set the script requirements for a task"""
request {
type: object
required: [
task
requirements
]
properties {
task {
description: "Task ID"
type: string
}
requirements {
description: "A JSON object containing requirements strings by key"
type: object
}
}
}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
completed {
"2.2" {
description: "Signal a task has completed"
request = {
type: object
required: [
task
]
properties.force = ${_references.force_arg} {
description: "If not true, call fails if the task status is not in_progress/stopped"
}
} ${_references.status_change_request}
response {
type: object
properties {
updated {
description: "Number of tasks updated (0 or 1)"
type: integer
enum: [ 0, 1 ]
}
fields {
description: "Updated fields names and values"
type: object
additionalProperties: true
}
}
}
}
}
ping {
"2.1" {
description: """ Refresh the task's last update time"""
request {
type: object
required: [
task
]
properties {
task {
description: "Task ID"
type: string
}
}
}
response {
type: object
additionalProperties: false
}
}
}
add_or_update_artifacts {
"2.6" {
description: """ Update an existing artifact (search by key/mode) or add a new one """
request {
type: object
required: [ task, artifacts ]
properties {
task {
description: "Task ID"
type: string
}
artifacts {
description: "Artifacts to add or update"
type: array
items { "$ref": "#/definitions/artifact" }
}
}
}
response {
type: object
properties {
added {
description: "Keys of artifacts added"
type: array
items { type: string }
}
updated {
description: "Keys of artifacts updated"
type: array
items { type: string }
}
}
}
}
}