Endpoint: GET /tasks

Query parameters

• filters object (required)

  Supported operators: and, or, and not.

  Supported attributes:

  • id
  • index
  • listIds
  • assigneesIds
  • deleted (not supported with query)
  • deletedAt (not supported with query)
  • deletedByUserId (not supported with query)
  • completed
  • completedAt
  • createdAt
  • createdUserId
  • lastActivityAt
  • parentTaskId
  • status
  • trashedAt
  • trashed
  • trashedByUserId
  • or any field template id

  Filter format:

  • values array of string/UUID/boolean/NONE_VALUE_ID (required)

    You can use NONE_VALUE_ID to ask for task with an empty attribute.

  • gt

    Use to find tasks with a date greater than the date provided.

    • date Date (see Date formats)

  • lt

    Use to find tasks with a date less than the date provided.

    • date Date (see Date formats)

  Full syntax

  type Operator = 'and' | 'or' | 'not'
  type AttributeName = 'id' | 'index' | 'listIds' | […]
  type Filter = {
  	values?: Array<string | UUID | boolean | NONE_VALUE_ID>,
  	gt?: Date,
  	lt?: Date,
  }
  type Filters = {
  	Operator: Array<Filters>,
  } | {
  	AttributeName: Filter,
  };
  

  Example 1 (simple query)

  {
    "status": {
      "values": ["backLog", "inProgress"]
    },
    "assigneeId": {
      "values": ["123e4567-e89b-12d3-a456-426655440000"]
    },
  	"completed": {
  	  "values": [false]
    },
  	"lastActivityAt": {
  		"values": [],
  		"gt": {"date":"2019-11-07T17:00:00.000Z"},
    }
  }
  

Example 2 (with operators)

{
  "or": [{
		"status": {
	    "values": ["backLog", "inProgress"]
	  },
	}, {
		"not": [{
			"assigneeId": {
		    "values": ["123e4567-e89b-12d3-a456-426655440000"]
		  },
		}],
	}
}

Filters with an empty values array will be ignored. For example,

{
  "or": [{
		"status": {
	    "values": []
	  },
	}, {
		"not": [{
			"assigneeId": {
		    "values": ["123e4567-e89b-12d3-a456-426655440000"]
		  },
		}],
	}
}

will be treated as

{
  "or": [{
		"not": [{
			"assigneeId": {
		    "values": ["123e4567-e89b-12d3-a456-426655440000"]
		  },
		}],
	}
}

• query string

  Full text search on the task

• limit number

  Maximum: 2000 (200 if query is provided)

  How many tasks the response should return.

  This limit applies to the tasks that match the filters/query. If you use expand to also fetch parentTasks/subTasks, the endpoint might return more than the limit you specified

• order array of objects

  How do you want the tasks to be ordered?

  • column string: what task attribute to order on. i.e. createdAt, lastActivityAt, deletedAt, …
  • direction string: ASC or DESC

• listOrderSourceId string or number

  • Is optional; when provided should be a view id, task id, or task index used to define ordering of tasks.

• expand array of string

  Possible values

  • parentTasks : find all the parent tasks of the tasks that match the filters
  • subTasks : find all the subtasks of the tasks that match the filters

• include array of string

  What you wish to include with the task. Options:

  • Assignees
  • CreatedByUser
  • CompletedByUser
  • DeletedByUser
  • Subscribers
  • Fields.User: user information for user fields
  • Lists
  • Status
  • Mentions
  • NotificationsSubscription
  • ParentTasks
  • SubtaskIds

• usePagination boolean

  • Is optional; Indicates whether paging should be kept active for the caller to explicitly fetch the next page of results.
  • There is a 1 minute window where paging is kept alive to request the next page of data before the point-in-time window for results expires.

Response:

The task object

Examples

Find tasks in back log

Request

curl <https://api.height.app/tasks> \\
	-G \\
  -H "Authorization: api-key secret_1234" \\
	-d filters='{"status":{"values":["backLog"]}}'