Jobs & Tasks

This API allows you to manage Jobs and Tasks within Unleash live. A Job is a high-level container that groups multiple Tasks. A Task represents a specific unit of work, such as a flight request or a manual inspection, and can include geographical boundaries (geofences) and associated missions.

Base URL: https://api.unleashlive.com

Authentication

All endpoints described in this section require a valid AWS Cognito JWT authentication token. The token must be passed in the x-amz-cognito-security-token header.

See the Authentication section for detailed instructions on generating tokens.

Job Endpoints

Create Job

POST /v1/job

Creates a new Job. The author of the job is assigned automatically.

Request Body

Key	Type	Description
`title`	String	`required` Name of the job
`description`	String	`required` Detailed description of the job
`userIds`	String[]	Array of User IDs to assign (must be in the same team)
`status`	UserTaskStatus[]	Initial status of the job

Example Request

{
  "title": "Weekly Transmission Line Inspection",
  "description": "Routine visual inspection of power lines in Sector 7G",
  "userIds": ["user-123", "user-456"]
}

Example Response

Returns a Job Object.

Code sample: create-job.js

Get Job

GET /v1/job/{jobId}

Retrieves a specific job by its ID.

Example Response

Returns a Job Object.

Code sample: get-job.js

List Assigned Jobs

GET /v1/job

Lists all jobs specifically assigned to your user context.

Example Response

[
  {
    "id": "job-12345",
    "title": "Weekly Transmission Line Inspection",
    "companyId": "comp-123",
    "teamId": "team-123",
    "ownerId": "user-123",
    "assignedId": "user-456",
    "createdAt": 1690000000000,
    "updatedAt": 1690000000000,
    "pk": "pk-1234",
    "sk": "sk-1234"
  }
]

Code sample: list-assigned-jobs.js

List Active Team Jobs

GET /v1/job/team

Lists all jobs across your active team (requires admin privileges).

Example Response

[
  {
    "id": "job-12345",
    "title": "Weekly Transmission Line Inspection",
    "companyId": "comp-123",
    "teamId": "team-123",
    "ownerId": "user-123",
    "assignedId": "user-456",
    "createdAt": 1690000000000,
    "updatedAt": 1690000000000,
    "pk": "pk-1234",
    "sk": "sk-1234"
  }
]

Code sample: list-team-jobs.js

Update Job

PATCH /v1/job/{jobId}

Updates specific fields of an existing job. Only the updated fields are returned in the response.

Request Body

Key	Type	Description
`title`	String	Job name
`description`	String	Job description
`userIds`	String[]	Assigned Users
`status`	UserTaskStatus[]	Job status

Example Response

{
  "updatedAt": 1690000005000,
  "title": "Monthly Transmission Line Inspection"
}

Code sample: update-job.js

Delete Job

DELETE /v1/job/{jobId}

Deletes a job from the database.

Example Response

Returns the deleted Job Object.

Code sample: delete-job.js

Assign User to All Job Tasks

PATCH /v1/job/{jobId}/task

Bulk assigns a specific user to every task currently attached to the job.

Request Body

Key	Type	Description
`assignedId`	String	`required` User ID

Code sample: assign-user-job-all-task.js

Task Endpoints

Create Task

POST /v1/task

Creates a new task and assigns it to a parent Job. It is also possible to bind a mission to the task during creation (or later via update) using the context object.

Request Body

Key	Type	Description
`jobId`	String	`required` ID of the parent job
`type`	TaskType	`required` Type of task
`description`	String	Task description
`status`	UserTaskStatus[]	Initial task status
`lat`	Number	Latitude coordinate
`lng`	Number	Longitude coordinate
`flightHistory`	FlightHistory[]	History of flights
`context`	TaskContext	Additional context/metadata

Example Request

{
  "title": "Inspect Tower Alpha",
  "description": "Visual inspection of top tier",
  "jobId": "job-12345",
  "type": "FLIGHT_REQUEST",
  "lat": -33.8635599,
  "lng": 151.2021623
}

Example Response

Returns a Task Object.

Code sample: create-task.js

Create Task with Mission

POST /v1/task/mission

Creates a task and simultaneously attaches a new flight mission in one unified request. The created mission can then be reused in other tasks by passing its ID to context.mission.id.

Request Example

Includes geofence polygons (via GeoJSON mapping) and a multi-point route.

{
  "jobId": "job-1234",
  "type": "FLIGHT_REQUEST",
  "name": "Lamp inspection",
  "desc": "Sample-mission",
  "speed": 2,
  "context": {
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [
              [
                [0, 0],
                [0, 1],
                [1, 1],
                [1, 0],
                [0, 0]
              ]
            ]
          },
          "properties": {}
        }
      ]
    }
  },
  "route": [
    {
      "pole": "Lamp 1",
      "lat": -33.863841,
      "lng": 151.200829,
      "altitude": 10.0,
      "actions": [{ "action": "TAKE_PHOTO" }]
    }
  ]
}

Example Response

Returns a Task Object representing the created task, containing the newly minted Mission ID within its context.

Code sample: create-task-mission.js

Create Task with Corridor Mission

POST /v1/task/mission-corridor

Creates a corridor mission task. Corridor missions are designed for linear flight paths with multiple waypoints, commonly used for infrastructure inspection, pipeline monitoring, or power line surveys.

Code sample: create-task-corridor-mission.js

Get Task

GET /v1/task/{taskId}

Retrieves a specific task from the database.

Example Response

Returns a Task Object.

Code sample: get-task.js

List Tasks

GET /v1/task
GET /v1/task/team
GET /v1/task/company
GET /v1/task/job/{jobId}

Retrieves lists of tasks based on the endpoint called:

/v1/task - Lists all tasks assigned to your user context.
/v1/task/team - Lists all tasks for your current team.
/v1/task/company - Lists all tasks across your company.
/v1/task/job/{jobId} - Lists all tasks attached to a specific job.

All endpoints return paginated data.

Query Parameters

Parameter	Description
`limit`	Maximum number of items to return.
`nextToken`	Pagination token generated by the previous request to fetch the next page.

Example Request

GET /v1/task?nextToken=abcd123&limit=50

Example Response

{
  "items": [
    {
      "id": "task-1234",
      "title": "Task title returning",
      "type": "FLIGHT_REQUEST",
      "status": "PUBLISHED",
      "jobId": "job-1234",
      "ownerId": "user-123",
      "teamId": "team-123",
      "companyId": "comp-123",
      "lat": 52.253057,
      "lng": 21.067224,
      "context": {
        "mission": {
          "id": "mission-1234",
          "route": [...]
        }
      },
      "createdAt": 1690000000000,
      "updatedAt": 1690000000000
    }
  ],
  "nextToken": "next-token-hex"
}

Code samples:

Update Task

PATCH /v1/task/{taskId}

Updates task fields. The API returns the entire new task object.

Example Response

Returns the updated Task Object.

Code sample: update-task.js

Delete Task

DELETE /v1/task/{taskId}

Removes a task from the database.

Example Response

Returns the deleted Task Object.

Code sample: delete-task.js

Reference

Job Object

Field	Type	Description
`id`	String	Unique identifier
`title`	String	Job title
`description`	String	Detailed description
`status`	String	Current status (e.g., `DRAFT`)
`totalTasks`	Integer	Total number of tasks in this job
`completedTasks`	Integer	Number of tasks marked completed
`userIds`	String[]	Array of assigned User IDs
`ownerId`	String	ID of the user who created the job
`teamId`	String	Team ID
`companyId`	String	Company ID
`createdAt`	Integer	Epoch timestamp of creation
`updatedAt`	Integer	Epoch timestamp of last update

Task Object

Field	Type	Description
`id`	String	Unique identifier
`jobId`	String	Parent Job ID
`type`	String	Task Type
`title`	String	Task title
`description`	String	Detailed description
`status`	String	Status
`context`	Object	Task Context Metadata
`lat`	Number	Latitude
`lng`	Number	Longitude
`ownerId`	String	ID of the user who created the job
`teamId`	String	Team ID
`companyId`	String	Company ID
`createdAt`	Integer	Epoch timestamp of creation
`updatedAt`	Integer	Epoch timestamp of last update

UserTaskStatus

Status	Description
`DRAFT`	Initial state, task is being prepared
`PUBLISHED`	Task is ready for assignment and execution
`IN_PROGRESS`	Task is currently being worked on
`COMPLETED`	Task has been successfully finished
`FAILED`	Task encountered issues and couldn’t complete

TaskType

Type
`FLIGHT_REQUEST`
`FLIGHT_REQUEST_MANUAL`

TaskContext

Key	Type	Description
`mission`	Partial `<Mission>`	Attached mission details
`asset`	Partial `<Asset>`	Attached asset details
`properties`	Record<String, String>	Additional metadata describing task
`geojson`	GeoJSON	GeoJSON geographical data

FlightHistory

Key	Type	Description
`flightStart`	Number	Start timestamp of the flight
`flightEnd`	Number	End timestamp of the flight
`distance`	Number	Distance traveled
`s3Path`	String	Path to the file storing the flight route

GeoJSON Configuration

GeoJSON context configuration allows you to define geographical shapes such as lists of points, lines, or polygons defining areas. It can also be used as boundaries that enforce flight restrictions or geofencing.

Supported Geometry Types:

Type	Description	Coordinates Format
`Polygon`	Closed area with boundaries	Array of `[longitude, latitude]`
`Point`	Single coordinate point	`[longitude, latitude]`
`LineString`	Linear path with multiple points	Array of `[longitude, latitude]`

Geofence Feature Properties:

When constructing your GeoJSON, you can attach properties to dictate bounding boxes and visual representations.

Key	Type	Description
`name`	String	Human-readable name for the geofenced area
`stroke`	String	Border color in hex format
`stroke-width`	Number	Border width in pixels
`stroke-opacity`	Number	Border opacity (0-1)
`fill`	String	Fill color in hex format
`fill-opacity`	Number	Fill opacity (0-1)
`geofence`	String	Geofence behavior: `inclusion` or `exclusion`

Example Exclusion Zone (Polygon)

{
  "properties": {
    "name": "Flight restriction zone",
    "stroke": "#ff0000",
    "stroke-width": 3,
    "stroke-opacity": 0.8,
    "fill": "#ff0000",
    "fill-opacity": 0.2,
    "geofence": "exclusion"
  }
}