_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[f]"
                type: string
            }
            requirements {
                description: "A JSON object containing requirements strings by key"
                type: object
            }
        }
    }
    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
        ]
    }
    execution {
        type: object
        properties {
            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[z]"""
                type: object
                additionalProperties: { type: integer }
            }
            framework {
                description: """Framework related to the task. Case insensitive. Mandatory for Training tasks. """
                type: string
            }
        }
    }
    task_status_enum {
        type: string
        enum: [
            created
            in_progress
            stopped
            published
            publishing
            closed
            failed
            unknown
        ]
    }
    task_type_enum {
        type: string
        enum: [
            training
            testing
        ]
    }
    last_metrics_event {
        type: object
        properties {
            metric {
                description: "Metric name"
                type: string
            }
            variant {
                description: "Variant name"
                type: string
            }
            type {
                description: "Event type"
                type: string
            }
            timestamp {
                description: "Event report time (UTC)"
                type: string
                format: "date-time"
            }
            iter {
                description: "Iteration number"
                type: integer
            }
            value {
                description: "Value"
                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: "Tags list"
                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_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"
                    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 tags. Use '-' prefix to exclude 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" }
                }
            }
        }
    }
}
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: "Tags list"
                    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: "Tags list"
                    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: "Tags list"
                    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: "Tags list"
                    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'"
            }
        } ${_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 }
                }
                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
                }
            }
        }
    }
}
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
                }
            }
        }
    }
}