@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Conduit API: Using Search Endpoints
2@group conduit
3
4Describes how to use search endpoints to find objects and read information.
5
6Overview
7========
8
9Many applications provide `search` endpoints, which are the primary way to
10get information about objects (like tasks) using the API.
11
12To read information about objects, you'll specify a //query// which describes
13which objects you want to retrieve. You can query for specific objects by
14ID, or for a list of objects satisfying certain constraints (for example, open
15tasks in a particular project).
16
17The best reference for a particular `search` endpoint is the Conduit API
18console. For example, you can find the console page for `maniphest.search` by
19navigating to {nav Conduit > maniphest.search} in the web UI. This page
20contains detailed information about the endpoint and how it can be used.
21
22
23Specifying a Query
24==================
25
26The simplest query you can use is no query at all: just make a request with
27no parameters. This will return the first page of visible objects. Most
28applications sort objects by creation date by default, so usually this is
29the 100 most recent objects.
30
31The easiest way to constrain results is to use a builtin query or a custom
32query that you build using the web UI. To do this, first issue the query in
33the web UI (for example, by clicking the builtin link on the left nav of the
34list view, or by submitting the query form).
35
36The results page will include a //query key// in the URL. For builtin queries,
37this is usually a human-readable term like `all` or `active`. For custom
38queries, it is a hash value which looks something like `MT0Rh0fB2x4I`.
39
40You can submit this key in the `queryKey` parameter to issue the exact same
41query via the Conduit API. This provides a simple way to build complex queries:
42just build the via the web UI, then reuse the same query in the API.
43
44If you need more control or want to build dynamic queries, use the
45`constraints` parameter to set constraints for individual query fields.
46
47For more details, consult the Conduit API console documentation for the
48method you're using. It includes documentation on all available constraints
49and lists builtin and saved query keys.
50
51
52Attachments
53===========
54
55By default, queries return basic information about objects. If you want more
56detailed information, most applications offer //attachments// which can let
57you retrieve more information.
58
59For example, subscribers and projects are not returned by default, but you
60can use subscribers to query them if you need this data.
61
62Asking for more data means a slower query and a larger result, so usually you
63should only ask for data you need.
64
65The Conduit API console page for each query method has detailed information
66on which attachments it supports.
67
68
69Next Steps
70==========
71
72Continue by:
73
74 - returning to the @{article:Conduit API Overview}.