Conduitmaniphest.search

API Method: maniphest.search

  • Unstable Method: ApplicationSearch methods are highly unstable.
  • Login Required: This method requires authentication. You must log in before you can make calls to it.
Returns
map<string, wild>
Errors
  • ERR-CONDUIT-CORE: See error message for details.
Description

This is a standard ApplicationSearch method which will let you list, query, or search for objects. For documentation on these endpoints, see Conduit API: Using Search Endpoints.

Builtin and Saved Queries

You can choose a builtin or saved query as a starting point for filtering results by selecting it with queryKey. If you don't specify a queryKey, the query will start with no constraints.

For example, many applications have builtin queries like "active" or "open" to find only active or enabled results. To use a queryKey, specify it like this:

Selecting a Builtin Query
{
  ...
  "queryKey": "active",
  ...
}

The table below shows the keys to use to select builtin queries and your saved queries, but you can also use any query you run via the web UI as a starting point. You can find the key for a query by examining the URI after running a normal search.

You can use these keys to select builtin queries and your configured saved queries:

Query KeyNameBuiltin
openOpen TasksBuiltin
allAll TasksBuiltin

Custom Query Constraints

You can apply custom constraints by passing a dictionary in constraints. This will let you search for specific sets of results (for example, you may want show only results with a certain state, status, or owner).

If you specify both a queryKey and constraints, the builtin or saved query will be applied first as a starting point, then any additional values in constraints will be applied, overwriting the defaults from the original query.

Specify constraints like this:

Example Custom Constraints
{
  ...
  "constraints": {
    "authors": ["PHID-USER-1111", "PHID-USER-2222"],
    "statuses": ["open", "closed"],
    ...
  },
  ...
}

This API endpoint supports these constraints:

KeyLabelTypeDescription
idsIDslist<int>Search for objects with specific IDs.
phidsPHIDslist<phid>Search for objects with specific PHIDs.
assignedAssigned Tolist<user>Search for tasks owned by a user from a list.
authorPHIDsAuthorslist<user>Search for tasks with given authors.
statusesStatuseslist<string>Search for tasks with given statuses.
prioritiesPrioritieslist<int>Search for tasks with given priorities.
fulltextContains WordsNot supported.
blockingBlockingNot supported.
blockedBlockedNot supported.
groupGroup ByNot supported.
createdStartCreated Afterepoch
createdEndCreated Beforeepoch
modifiedStartUpdated Afterepoch
modifiedEndUpdated Beforeepoch
subscribersSubscriberslist<user>Search for objects with certain subscribers.
projectsProjectslist<project>Search for objects associated with given projects.

Result Ordering

Use order to choose an ordering for the results.

Either specify a single key from the builtin orders (these are a set of meaningful, high-level, human-readable orders) or specify a custom list of low-level columns.

To use a high-level order, choose a builtin order from the table below and specify it like this:

Choosing a Result Order
{
  ...
  "order": "newest",
  ...
}

These builtin orders are available:

KeyDescriptionColumns
priorityPrioritypriority, subpriority, id
updatedDate Updated (Latest First)updated, id
outdatedDate Updated (Oldest First)-updated, -id
newestCreation (Newest First)id
oldestCreation (Oldest First)-id
titleTitletitle, id

You can choose a low-level column order instead. To do this, provide a list of columns instead of a single key. This is an advanced feature.

In a custom column order:

  • each column may only be specified once;
  • each column may be prefixed with - to invert the order;
  • the last column must be a unique column, usually id; and
  • no column other than the last may be unique.

To use a low-level order, choose a sequence of columns and specify them like this:

Using a Custom Order
{
  ...
  "order": ["color", "-name", "id"],
  ...
}

These low-level columns are available:

KeyUnique
idYes
priorityNo
ownerNo
statusNo
projectNo
titleNo
subpriorityNo
updatedNo

Object Fields

Objects matching your query are returned as a list of dictionaries in the data property of the results. Each dictionary has some metadata and a fields key, which contains the information abou the object that most callers will be interested in.

For example, the results may look something like this:

Example Results
{
  ...
  "data": [
    {
      "id": 123,
      "phid": "PHID-WXYZ-1111",
      "fields": {
        "name": "First Example Object",
        "authorPHID": "PHID-USER-2222"
      }
    },
    {
      "id": 124,
      "phid": "PHID-WXYZ-3333",
      "fields": {
        "name": "Second Example Object",
        "authorPHID": "PHID-USER-4444"
      }
    },
    ...
  ]
  ...
}

This result structure is standardized across all search methods, but the available fields differ from application to application.

These are the fields available on this object type:

KeyTypeDescription
titlestringThe title of the task.
authorPHIDphidOriginal task author.
ownerPHIDphid?Current task owner, if task is assigned.
statusmap<string, wild>Information about task status.
prioritymap<string, wild>Information about task priority.
spacePHIDphid?PHID of the policy space this object is part of.
dateCreatedintEpoch timestamp when the object was created.
dateModifiedintEpoch timestamp when the object was last updated.
policymap<string, wild>Map of capabilities to current policies.

Attachments

By default, only basic information about objects is returned. If you want more extensive information, you can use available attachments to get more information in the results (like subscribers and projects).

Generally, requesting more information means the query executes more slowly and returns more data (in some cases, much more data). You should normally request only the data you need.

To request extra data, specify which attachments you want in the attachments parameter:

Example Attachments Request
{
  ...
  "attachments": {
    "subscribers": true
  },
  ...
}

This example specifies that results should include information about subscribers. In the return value, each object will now have this information filled out in the corresponding attachments value:

Example Attachments Result
{
  ...
  "data": [
    {
      ...
      "attachments": {
        "subscribers": {
          "subscriberPHIDs": [
            "PHID-WXYZ-2222",
          ],
          "subscriberCount": 1,
          "viewerIsSubscribed": false
        }
      },
      ...
    },
    ...
  ],
  ...
}

These attachments are available:

KeyNameDescription
subscribersSubscribersGet information about subscribers.
projectsProjectsGet information about projects.

Paging and Limits

Queries are limited to returning 100 results at a time. If you want fewer results than this, you can use limit to specify a smaller limit.

If you want more results, you'll need to make additional queries to retrieve more pages of results.

The result structure contains a cursor key with information you'll need in order to fetch the next page of results. After an initial query, it will usually look something like this:

Example Cursor Result
{
  ...
  "cursor": {
    "limit": 100,
    "after": "1234",
    "before": null,
    "order": null
  }
  ...
}

The limit and order fields are describing the effective limit and order the query was executed with, and are usually not of much interest. The after and before fields give you cursors which you can pass when making another API call in order to get the next (or previous) page of results.

To get the next page of results, repeat your API call with all the same parameters as the original call, but pass the after cursor you received from the first call in the after parameter when making the second call.

If you do things correctly, you should get the second page of results, and a cursor structure like this:

Second Result Page
{
  ...
  "cursor": {
    "limit": 5,
    "after": "4567",
    "before": "7890",
    "order": null
  }
  ...
}

You can now continue to the third page of results by passing the new after cursor to the after parameter in your third call, or return to the previous page of results by passing the before cursor to the before parameter. This might be useful if you are rendering a web UI for a user and want to provide "Next Page" and "Previous Page" links.

If after is null, there is no next page of results available. Likewise, if before is null, there are no previous results available.

Call Method

Enter parameters using JSON. For instance, to enter a list, type: ["apple", "banana", "cherry"]

optional string
optional map<string, wild>
optional map<string, bool>
optional order
optional string
optional string
optional int (default = 100)

Examples

Use the Conduit API Tokens panel in Settings to generate or manage API tokens.
$ echo <json-parameters> | arc call-conduit --conduit-uri https://phabricator.cooltrainer.org/ --conduit-token <conduit-token> maniphest.search