RESTTasks

Create task

Creates a new Task in the system with the specified parameters. This method initiates a new task with a unique ID (either provided or auto-generated), sets the initial task state to STATUS_CREATED, and establishes task ownership. The task can be assigned to a specific agent through the Relations field. Once created, a task enters the lifecycle workflow and can be tracked, updated, and managed through other Tasks API endpoints.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
taskIdstringOptional

If non-empty, will set the requested Task ID, otherwise will generate a new random GUID. Will reject if supplied Task ID does not match [A-Za-z0-9_-.]36.

descriptionstringOptional
Longer, free form human readable description of this Task.
specificationobjectOptional
The path for the Protobuf task definition, and the complete task data.
authorobjectOptional
A Principal is an entity that has authority over this task.
relationsobjectOptional
Any relationships associated with this Task, such as a parent Task or an assignee this Task is designated to for execution.
isExecutedElsewherebooleanOptional
If set, then the service will not trigger execution of this task on an agent. Useful for when ingesting tasks from an external system that is triggering execution of tasks on agents.
initialEntitieslist of objectsOptional
Indicates an initial set of entities that can be used to execute an entity aware task. For example, an entity Objective, an entity Keep In Zone, etc.
displayNamestringOptionalDeprecated

Human readable display name for this Task, should be short (<100 chars).

Response

Task creation was successful
versionobject
Version of this task.
displayNamestring

DEPRECATED: Human readable display name for this task, should be short (<100 chars).

specificationobject
The path for the Protobuf task definition, and the complete task data.
createdByobject
Records who created this task. This field will not change after the task has been created.
lastUpdatedByobject
Records who updated this task last.
lastUpdateTimedatetime
Records the time of last update.
statusobject
The status of this task.
scheduledTimedatetime
If the task has been scheduled to execute, what time it should execute at.
relationsobject

Any related Tasks associated with this, typically includes an assignee for this task and/or a parent.

descriptionstring
Longer, free form human readable description of this task
isExecutedElsewhereboolean
If set, execution of this task is managed elsewhere, not by Task Manager. In other words, task manager will not attempt to update the assigned agent with execution instructions.
createTimedatetime
Time of task creation.
replicationobject
If populated, designates this to be a replicated task.
initialEntitieslist of objects

If populated, indicates an initial set of entities that can be used to execute an entity aware task For example, an entity Objective, an entity Keep In Zone, etc. These will not be updated during execution. If a taskable agent needs continuous updates on the entities from the COP, can call entity-manager, or use an AlternateId escape hatch.

ownerobject
The networked owner of this task. It is used to ensure that linear writes occur on the node responsible for replication of task data to other nodes running Task Manager.
retryStrategyobject
Sets an optional try strategy for tasks. Use this option to control how Lattice attempts to retry delivery of tasks to assets with intermittent access or network connectivity to your environment.
deliveryStateobject
The current delivery state of a task.

Errors

400
Bad Request Error
401
Unauthorized Error